# KC AgentDock MCP

一个可由 Cursor 云端代理直接下载的单文件 MCP。它把两条能力合并到同一个 stdio MCP 中：

- 保留本机 **KC Chat Panel 6.9.1** 的会话交互：`reply_message` → `wait_message`。
- 转发本机 **AgentDock** 的电脑操作工具，统一使用 `agentdock_` 前缀。

云端不直接访问 KC 的本地队列。所有公网流量只进入已有的 AgentDock Streamable HTTP `/mcp` 端点，再由 AgentDock 调用本机注册的 `kc-chat` 动态 MCP。

## 链路

```text
Cursor Cloud Agent
  └─ kc-agentdock-mcp.cjs（stdio）
       └─ HTTPS + Bearer → AgentDock /mcp（本机公网入口）
            ├─ AgentDock 内置电脑工具
            └─ kc-chat 动态 MCP
                 └─ KC Chat Panel 本地会话队列
```

KC 面板本身无需修改，也不需要新聊天 UI。用户仍在 KC 面板中新建 session，并把 sessionId 发给云端子代理。

## 本机前置配置

本机 AgentDock 中需要有一个名为 `kc-chat` 的动态 MCP：

| 字段 | 值 |
|---|---|
| transport | `stdio` |
| command | `node` |
| args[0] | `C:\Users\zgg20\.cursor\kc-mcp\mcp-server.cjs` |
| args[1] | `--queue-root=C:\Users\zgg20\.cursor\kc-mcp-messages` |
| cwd | `C:\Users\zgg20\.cursor\kc-mcp` |
| timeout | `300000` ms |

AgentDock 公网端点必须使用 HTTPS，并开启认证。不要把 `/mcp` 无认证暴露到公网，因为它包含电脑命令、文件修改和 Git 等高权限工具。

## 云端安装

要求 Node.js 20 或更高版本。

1. 下载 `kc-agentdock-mcp.cjs` 并核对发布方给出的 SHA-256。
2. 在 Cursor Cloud Secrets 中配置：
   - `AGENTDOCK_URL=https://你的公网域名/mcp`
   - `AGENTDOCK_TOKEN=你的 AgentDock Bearer token`
3. 在目标仓库中运行：

```bash
node /tmp/kc-agentdock-mcp.cjs --install "$PWD"
```

安装器会：

- 复制单文件程序到 `.cursor/tools/kc-agentdock-mcp.cjs`；
- 合并 `.cursor/mcp.json`，保留 JSONC 注释和已有 MCP；
- 修改现有配置前创建可恢复的时间戳备份；
- 只写环境变量插值，不把 token 写入仓库。

随后启动或重启 Cloud Agent run，并在启动时启用 `kc-agentdock`。Cursor Cloud 的 MCP 是按 run 选择的；已经运行中的代理通常不会因为写入 `mcp.json` 就立刻获得新工具。

## 已运行子代理的即时兼容模式

若必须让当前 run 立即接入，可让子代理保持一个终端会话：

```bash
node /tmp/kc-agentdock-mcp.cjs --kc-loop '<SESSION_ID>'
```

程序先输出 `ready`，随后等待 KC 消息。每次输出 `message` 事件后，向该进程 stdin 写一行 JSON：

```json
{"content":"回复正文","agentStatus":"ready","suggestions":["运行测试","查看修改"]}
```

程序会自动调用 `reply_message`，再继续 `wait_message`；`[POLL_TICK]` 会在内部自动续等。写入 `{"action":"stop"}` 可结束。

这只是当前 run 无法热加载 MCP 时的兼容路径。新 run 应使用原生 MCP 工具。

## 工具暴露方式

默认直接暴露 8 个 KC 聊天工具：

- `wait_message`
- `reply_message`
- `list_sessions`
- `send_to_session`
- `broadcast_message`
- `recall_message`
- `create_agent`
- `list_groups`

AgentDock 的全部内置工具以 `agentdock_` 前缀暴露，例如：

- `agentdock_exec_command`
- `agentdock_file_edit`
- `agentdock_git_read`
- `agentdock_mcp_tool_search`
- `agentdock_mcp_tool_inspect`
- `agentdock_mcp_tool_call`

因此，未直接展开的 KC 高级工具仍可通过 AgentDock 的动态 MCP 搜索/检查/调用三件套使用。若确实希望把 KC 的 45 个工具全部直接暴露，可设置 `KC_TOOLSET=all`；这会增加启动发现时间和模型工具上下文。

## KC 对话契约

云端代理拿到 sessionId 后必须遵循：

1. 每次可见回复调用 `reply_message`，否则内容不会进入 KC 面板历史。
2. 紧接着调用 `wait_message`。
3. 收到 `[POLL_TICK]` 时立即再次调用 `wait_message`。
4. 只有用户明确结束会话时才退出循环。

这些规则同时写入 MCP server instructions 和关键工具说明中。

## 配置项

| 环境变量 | 默认值 | 说明 |
|---|---:|---|
| `AGENTDOCK_URL` | 必填 | 完整公网 `/mcp` URL；根 URL 会自动补 `/mcp` |
| `AGENTDOCK_TOKEN` | 必填 | Bearer token，不会写入状态和日志 |
| `AGENTDOCK_AUTHORIZATION` | 空 | 可替代 token，传完整 Authorization 值 |
| `KC_SERVER` | `kc-chat` | AgentDock 中的动态 MCP 名称 |
| `KC_TOOLSET` | `chat` | `chat`、`all` 或 `none` |
| `KC_TOOLS` | 空 | 逗号分隔的直接 KC 工具白名单，优先于 toolset |
| `AGENTDOCK_TOOL_PREFIX` | `agentdock_` | AgentDock 工具名前缀 |
| `AGENTDOCK_EXCLUDE_TOOLS` | 空 | 逗号分隔的 AgentDock 工具排除列表 |
| `AGENTDOCK_REQUEST_TIMEOUT_MS` | `360000` | 上游工具调用超时 |

公网非回环 HTTP 会被拒绝。仅本地测试可用 `http://127.0.0.1`；不建议设置 `AGENTDOCK_ALLOW_INSECURE_HTTP=1`。

## 自检和命令行调用

```bash
node kc-agentdock-mcp.cjs --doctor
node kc-agentdock-mcp.cjs --list-tools
node kc-agentdock-mcp.cjs --call bridge_status '{}'
```

`--doctor` 只输出脱敏后的端点、版本和工具数量，不输出 token。

## 安全边界

- stdio MCP 运行在 Cloud Agent VM 中，传给它的环境变量对该 VM 内的进程可见。请使用 Cursor Secrets，不要在提示词、下载 URL、仓库或命令历史中粘贴 token。
- AgentDock 工具可以操作本机文件和执行命令。只把凭据交给你信任的代理/run，完成后按需轮换 token。
- 发布文件应先核对 SHA-256；安装器不会静默下载其他代码。
- 默认只直出核心 KC 工具，以降低提示注入面和工具上下文体积；AgentDock 完整权限仍然存在。

## 参考实现

- AgentDock：<https://github.com/uvwt/agentdock>
- AgentDock MCP client guide：<https://uvwt.github.io/agentdock-docs/docs/guides/mcp-clients>
- Cursor MCP：<https://cursor.com/docs/mcp>
- Cursor Cloud setup：<https://cursor.com/docs/cloud-agent/setup>

本项目使用官方 MCP TypeScript SDK，并针对 AgentDock 0.7.2 与 KC Chat Panel 6.9.1 的协议进行了验证。