claude-code-controller-mcp

MCP server để spawn, điều khiển và quan sát các tiến trình Claude Code CLI từ bất kỳ MCP client nào (Claude Code chính nó, Claude Desktop, hoặc IDE). Mục tiêu: dùng MCP làm "control plane" cho Claude Code — chạy nhiều phiên song song, gửi prompt vào thread đang sống, kill tiến trình, liệt kê transcripts cũ.

Cách nó hoạt động

Server quản lý một danh sách Map<processId, child_process>. Mỗi spawn:

1. Chạy claude --print --input-format=stream-json --output-format=stream-json --include-partial-messages với các flag tuỳ chọn.
2. Giữ stdin pipe mở — claude_send_message ghi 1 JSON line vào stdin để gửi thêm prompt.
3. Parse từng dòng stdout (stream-json events), nhồi vào ring buffer (mặc định 5000 events).
4. Trích session_id từ events để giúp client resume sau này.

claude_list_sessions đọc thẳng ~/.claude/sessions/*.json (live PID files) và ~/.claude/projects/<encoded-cwd>/ (transcripts persisted).

Tools

| Tool | Mô tả | |---|---| | claude_run_oneshot | claude -p <prompt>, trả stdout/stderr | | claude_spawn_session | Spawn process nền stream-json, trả processId | | claude_send_message | Gửi prompt vào session đang chạy | | claude_get_output | Đọc events đã buffer + tail stdout/stderr | | claude_list_processes | Liệt kê process do controller spawn | | claude_list_sessions | Liệt kê session trên đĩa (live + transcripts) | | claude_kill_process | Kill theo processId hoặc OS pid | | claude_resume_session | Spawn mới, resume --resume <sessionId> | | claude_fork_session | Resume + --fork-session | | claude_purge_project | claude project purge <path> | | claude_mcp | Passthrough claude mcp list/get/add/remove | | claude_doctor | claude doctor | | claude_list_transcripts | List tất cả file .jsonl (= cuộc trò chuyện) của một project, sort mới nhất, kèm preview | | claude_read_transcript | Đọc nguyên văn nội dung user/assistant của bất kỳ session nào (kể cả đang chạy trong VSCode / terminal khác). Hỗ trợ sinceUuid để poll-tail |

Yêu cầu

• Node.js 18+
• Claude Code binary đã cài (tìm tự động ở ~/.claude/downloads/claude-*.exe trên Windows, hoặc set CLAUDE_CODE_BIN).

Cài đặt

cd F:\Redon\DuAn\project01\claude-code-controller-mcp
npm install
npm run build

Khởi động (standalone, để test)

# Chạy server trên stdio (sẽ chờ JSON-RPC từ stdin)
.\scripts\start-mcp.ps1

# Hoặc trực tiếp
node dist/server.js

Đăng ký với Claude Code

# Tự động: tìm claude.exe, gọi `claude mcp add`
.\scripts\register-with-claude.ps1

# Kiểm tra
& "$env:USERPROFILE\.claude\downloads\claude-2.1.143-win32-x64.exe" mcp list

Hoặc thủ công:

& <claude.exe> mcp add --transport stdio claude-code-controller `
    powershell -- -NoProfile -ExecutionPolicy Bypass `
    -File "F:\Redon\DuAn\project01\claude-code-controller-mcp\scripts\start-mcp.ps1"

Đăng ký với Claude Desktop

Thêm vào claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code-controller": {
      "command": "node",
      "args": ["F:\\Redon\\DuAn\\project01\\claude-code-controller-mcp\\dist\\server.js"],
      "env": {
        "CLAUDE_CODE_BIN": "C:\\Users\\<you>\\.claude\\downloads\\claude-2.1.143-win32-x64.exe"
      }
    }
  }
}

Biến môi trường

| Var | Ý nghĩa | |---|---| | CLAUDE_CODE_BIN | Đường dẫn tuyệt đối tới claude binary | | CLAUDE_HOME | Override ~/.claude (mặc định: home user) | | CLAUDE_CONTROLLER_CWD | Mặc định cwd khi spawn |

Ví dụ luồng dùng (qua MCP client)

// 1. Spawn phiên nền
{"tool":"claude_spawn_session","args":{
  "cwd":"F:\\Redon\\DuAn\\project01\\redai-v201-be-app",
  "prompt":"Liệt kê các file controller trong src/",
  "model":"sonnet","effort":"medium"
}}
// → { processId: "abc-...", pid: 12345, sessionId: null, status: "starting" }

// 2. Đợi rồi đọc output
{"tool":"claude_get_output","args":{"processId":"abc-...","tailLines":50}}

// 3. Gửi follow-up
{"tool":"claude_send_message","args":{
  "processId":"abc-...",
  "prompt":"Bây giờ tóm tắt từng controller làm gì."
}}

// 4. Khi xong, kill
{"tool":"claude_kill_process","args":{"processId":"abc-..."}}

Hạn chế đã biết

• Chỉ stream-json mode: không chạy được TUI / slash command interactive của Claude Code. Để có TUI, cần thêm node-pty (v2 sẽ làm nếu cần).
• Buffer trong RAM: 5000 events/process. Process exit sẽ pruned sau 5 phút.
• Windows-first: bash path có nhưng chưa test kỹ trên Linux/macOS — findClaudeBinary() đã có nhánh POSIX.
• claude_purge_project truyền --yes; nếu CLI version của bạn không hỗ trợ flag đó, sẽ treo chờ confirm — sửa lại bằng cách thêm < redirect "y\n" hoặc bỏ flag.

Thư mục

src/
├── server.ts            # MCP server + 12 tool handlers
├── config.ts            # Find claude binary, paths
├── process-manager.ts   # Spawn/track child processes, stream-json parser
├── session-tracker.ts   # Read ~/.claude/sessions, projects
└── shell/powershell.ts  # ad-hoc PowerShell/Bash exec helpers
scripts/
├── start-mcp.ps1        # Launcher dùng làm MCP "command"
├── register-with-claude.ps1
└── smoke-test.ps1