whalecode-mcp

WhaleCode MCP 服务器：把主机（Cursor 等）的工具调用转发到本机已打开的 WhaleCode 窗口。运行路径与侧栏 Composer 相同，审批、hooks、行内审阅仍然生效。

前提：

• Node.js >= 18
• 本机已启动带 WhaleCode 扩展的 IDE，且至少打开一个工作区（扩展会在 onStartupFinished 后拉起 localhost bridge）

本包零运行时依赖，只用 Node 内置模块（http / fs / path / os）。

安装

npm install -g whalecode-mcp

配置 MCP 主机

Cursor（.cursor/mcp.json 可用 npx：

{
  "mcpServers": {
    "whalecode": {
      "command": "npx",
      "args": ["-y", "whalecode-mcp@latest"]
    }
  }
}

传输为 JSON-RPC 2.0、按行分隔的 STDIO（protocolVersion: 2024-11-05，serverInfo.name: whalecode）。配置完成后主机会发现下面三个工具。

可用工具

list_sessions

列出当前存活的 WhaleCode 窗口。无参数。 多窗口时先用这个拿 sessionId，再交给 run_agent。

run_agent

向一个已打开的窗口发聊天，并同步轮询直到终态、取消、出错或超时（轮询间隔 500ms）。成功后会聚焦 WhaleCode 聊天视图。

{
  "text": "请解释这个函数的实现逻辑",
  "workspace": "/path/to/project",
  "mode": "agent",
  "model": "deepseek-v4-flash",
  "newChat": true
}

| 参数 | 类型 | 必填 | 说明 | | ---------------- | ------- | ---- | ---------------------------------------------------------------------------------- | | text | string | 是 | 发给 WhaleCode 的内容（空串会报错） | | mode | string | 否 | agent / ask / plan / multitask / project / debug。省略则用窗口当前模式 | | model | string | 否 | 模型 id 或显示名。省略则用「推荐」列表里第一个当前可用的模型 | | workspace | string | 否 | 按工作区路径选窗口，默认 MCP 进程 cwd | | sessionId | string | 否 | 精确指定窗口，优先于 workspace | | conversationId | string | 否 | 切到已有会话再发；会话不存在则失败 | | newChat | boolean | 否 | true 时先开新会话（优先于 conversationId） | | timeoutMs | number | 否 | 等待终态的上限，默认 900000（15 分钟）。须 > 0 |

窗口路由（pickSession，多匹配时不猜）：

1. 传了 sessionId → 精确匹配，否则报错并带上候选窗口
2. 否则用 workspace（默认 cwd）匹配：目标路径等于某 workspaceFolders 项，或是其子路径（/proj 能匹配 /proj/src，不能匹配 /proj-extra）
3. 命中 1 个 → 使用；0 个 → 报「没有打开的窗口」；多个 → 报错，要求传入 sessionId，sessions 里是候选公开信息

模型解析：

• 传了 model：按 picker 的完整 id、modelId、裸 id、名称（忽略大小写）匹配；对不上则 模型不可用：…
• 未传：按推荐顺序取第一个可用项：deepseek-v4-flash → qwen3-5-397B → kimi-26。一个都没有则报错，提示在设置里启用其中一个
• auto 不会被选中

会话：newChat → 新建；否则若给了 conversationId 必须已存在；再否则用当前会话，没有当前会话则新建。

终态返回：

{
  "runId": "run_1710000000000_ab12cd",
  "conversationId": "conv_456",
  "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "finished",
  "model": "provider::deepseek-v4-flash",
  "assistantText": "……",
  "toolSummary": ["search ok: 找到 3 个结果", "read failed: …"],
  "needsApproval": false
}

| status | 含义 | | ----------- | ------------------------------------------------------- | | finished | 正常结束 | | cancelled | 被 cancel_run 或 IDE 取消 | | error | 启动失败或运行出错，见 error | | timeout | 超过 timeoutMs 仍为 running（工具结果标 isError） |

超时额外带 pendingApproval。若窗口在等用户点审批，needsApproval 为 true；MCP 不会代批，需要人在 IDE 里处理，否则会一直 running 直到超时。toolSummary 来自已完成的 tool-call（name ok/failed: 首行摘要）。

cancel_run

取消一次仍在跑的 run_agent。

{ "runId": "run_1710000000000_ab12cd" }

| 参数 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ------------------------------------------------------------- | | runId | string | 是 | run_agent 返回的 id | | sessionId | string | 否 | 目标窗口。省略则先查本 MCP 进程启动过的 run，再向各活窗口探测 |

定位顺序：显式 sessionId → 本进程 runId 缓存 → 对其余窗口 GET /v1/runs/:id（404 跳过）。找不到则 { "error": "run not found: …" }。

成功：{ "ok": true, "runId": "…", "status": "cancelled", "sessionId": "…" }。已经结束的 run 会原样返回其当前 status。

工作原理

MCP Host
  │  JSON-RPC 2.0（一行一条）over STDIO
  ▼
whalecode-mcp
  │  读 ~/.whalecode/sessions/*.json
  │  HTTP 127.0.0.1:<port>  +  Authorization: Bearer <token>
  ▼
WhaleCode 扩展 bridge
  │  与 Composer 同一条 runExternal
  ▼
侧栏 / 编辑器聊天