# Model Worker MCP

Model Worker MCP 是一个本机、与 provider 和 model 解耦的 MCP server。coordinator（发起和协调任务的 MCP client）通过短调用提交任务；worker daemon（持有队列、session 和执行状态的后台进程）会在 client 断开后继续执行。V1 以 Claude Agent SDK harness 驱动 `kimi-k3`，公共协议不绑定该实现。

## 快速开始

需要 Windows、Node.js 22.x，以及可用的 Claude Code runtime。安装依赖并构建：

```powershell
npm ci
npm run build
npm link
```

让启动 MCP client 的用户环境包含 `MODEL_GATEWAY_API_KEY`。项目只把这个变量名作为公共 credential 接口；配置文件和命令示例都不保存 credential 值。然后注册推荐的 strict stdio bootstrap：

```powershell
codex mcp add model-worker -- model-worker-mcp stdio --request-integrity required
claude mcp add --scope user model-worker -- model-worker-mcp stdio --request-integrity required
```

这两条命令会修改对应 client 的用户配置。strict 模式要求 coordinator 在写请求中提供由本地 `request-digest` 命令计算的摘要，以便 daemon 在产生副作用前拒绝被改写的参数；摘要不是身份认证。执行前应先阅读[客户端注册](docs/client-registration.md)，确认摘要工作流、兼容模式、scope 和现有同名 server；开发测试只使用临时配置目录。

## 更换网关或模型

端点和模型不写死在代码里。daemon 启动时读取 `<数据根>\model-registry.json`，文件不存在则使用内置默认值（SFKey + `kimi-k3`）。换中转站或换模型是复制 `config/model-registry.example.json` 到数据根、改 `endpoints` 与 `upstream_model_id`、再 `model-worker-mcp daemon restart`，不需要重新构建。

凭据引用必须落在 `MODEL_GATEWAY_` 环境变量命名空间内，端点必须是 https；文档不合法时 daemon 明确失败而不会退回默认值。细节见[运行与维护](docs/operations.md)。

## Capability profiles

Capability profile 是 daemon 强制执行的一组工作区和工具权限，不只是 prompt 建议。

- `text_only`：处理文本和已冻结的附件，不接收 workspace。
- `workspace_read`：读取授权 workspace；不给模型 shell 或写入工具。
- `patch_proposal`：在独立 Git clone 中修改和测试，返回 patch；不会自动改动原工作区。

## MCP tools

- `model_list`：列出可用 model binding 和能力声明。
- `model_health`：做本地健康检查。V1 production daemon 固定禁用 live probe；opt-in live probe 只存在于独立测试 harness。
- `task_submit`：创建 session 并异步提交首个 task。
- `task_continue`：在同一 session head 后继续一轮，不能提高权限。
- `task_get`：按 cursor 查询状态、事件、结果和 artifact chunk。
- `task_cancel`：请求取消 queued 或 active task；对 terminal task 幂等。

## 继续阅读

- [运行与维护](docs/operations.md)
- [客户端注册](docs/client-registration.md)
- [设计规格](docs/superpowers/specs/2026-08-01-model-worker-mcp-design.md)
- [实现计划](docs/superpowers/plans/2026-08-01-model-worker-mcp-implementation.md)