Repository navigation
MCP.zh cn
C-F0x edited this page Oct 26, 2026
·
1 revision
CompileGateway 在 Daemon 内部以 Rust 原生实现了 Model Context Protocol (MCP) 服务,并在独立的端口上对外暴露,使 AI Agent(Claude Code、Cursor、Cline、Codex 等)能够结构化地编排和执行远程跨机编译全链路。
┌───────────────────────────────────────────────────────────┐
│ CompileGateway │
│ │
│ HTTP 主服务 (:65251) 内置 MCP 原生服务 (:3994) │
│ ├─ WebUI 网页 ├─ 42 个专用工具 │
│ ├─ cgw 命令行客户端 ├─ 8 份核心资源 │
│ └─ REST 数据接口 └─ 3 个 Prompt 引导模板 │
└──────────────┬─────────────────────────────┬──────────────┘
│ │
(本地环回 / 局域网) Streamable HTTP / stdio 管道
│ │
浏览器 / 终端控制台 AI 编程助手 / Agent 客户端
- Daemon 原生内置(Rust):无须依赖外部 Node.js 运行时即可提供 MCP 服务;启动 Daemon 时 MCP 服务随同就绪。
-
独立服务端口:运行在独立的端口(默认
3994,由mcp.port与mcp.listen配置),MCP 配置变更支持即时热重载,无须重启 Daemon。 -
传输协议:标准 Streamable HTTP(
POST /mcp,无状态 JSON-RPC 2.0)。 -
可选 stdio 转发桥(
mcp/):附带轻量 Node.js stdio 转发脚本,仅用于适配只支持标准输入输出管道的客户端(如 Claude Desktop);支持 HTTP 传输的客户端可直连端点。
对于支持 HTTP 协议传输的 MCP 客户端(如 Cursor、Cline),直接配置端点地址:
{
"mcpServers": {
"compilegateway": {
"url": "http://127.0.0.1:3994/mcp"
}
}
}若通过局域网/公网连接启用了鉴权的 Daemon,在请求头中附带 HTTP Basic 凭据:
{
"mcpServers": {
"compilegateway": {
"url": "http://192.168.1.20:3994/mcp",
"headers": {
"Authorization": "Basic YWxpY2U6c2VjcmV0"
}
}
}
}Note
当在 WAN 模式下启用鉴权时,MCP 对 HTTP Basic 凭据实施基于客户端 IP 的防爆破限流保护。连续密码尝试失败将触发冷却退避,并返回 HTTP 429 与 JSON-RPC 错误码 -32001 及 Retry-After 响应头。
对于必须通过 stdio 管道启动的桌面应用(如 Claude Desktop):
{
"mcpServers": {
"compilegateway": {
"command": "node",
"args": ["/path/to/CompileGateway/mcp/dist/index.js"]
}
}
}转发桥会自动读取共享目录 CGW_HOME 中的 runtime.json 或 $CGW_URL 环境变量以定位正在运行的 Daemon。
所有工具参数 Schema 直接由 Rust 核心结构体通过 schemars 自动导出,保证 MCP 工具契约与底层的 REST API 绝对一致。
| 工具名 | 用途说明 |
|---|---|
cgw_status |
查看 Daemon 状态、版本、监听范围、语言、访问地址与 MCP 状态 |
cgw_get_config |
读取当前完整系统配置 |
cgw_set_config |
修改配置(mcp.*、allowedRoots、hostLock、loginIntervalSeconds 等) |
| 工具名 | 用途说明 |
|---|---|
cgw_list_clients |
列出已登记的 SSH 目标机(客户机)列表(包含主机参数、基准目录与 hostLock 状态) |
cgw_save_client |
新增或编辑客户机连接配置(支持密钥、密码认证、基准目录与单机独占 hostLock 开关) |
cgw_delete_client |
删除客户机配置 |
cgw_test_client |
执行真实 SSH 连接测试并核对 TOFU 主机指纹 |
cgw_detect_env |
执行单次往返远程环境探测(检测 Xcode 多版本/License、JDK、Gradle、Rust 等) |
| 工具名 | 用途说明 |
|---|---|
cgw_list_projects |
列出项目登记及当前运行状态 |
cgw_browse |
浏览宿主机受控根目录(allowedRoots)下的子目录,供挑选源码路径 |
cgw_create_project |
登记宿主机源码目录为项目并绑定客户机 |
cgw_delete_project |
移除项目登记(保留所有源码与产物文件) |
cgw_tree |
受控遍历项目远端(remote)或宿主机侧(host)文件树 |
| 工具名 | 用途说明 |
|---|---|
cgw_list_tasks |
列出项目的全部触发任务(涵盖 7 种原子类型) |
cgw_save_task |
保存/更新项目任务(校验相对路径与输入输出契约) |
cgw_delete_task |
删除指定任务(自动清理批量工作流中的无效引用) |
cgw_preview_task |
预渲染构建命令与展开路径(Dry-run 校验,不实际执行) |
cgw_run_task |
触发执行指定任务(支持 enqueue: true 排队;排队计划持久化落盘,Daemon 重启自动恢复执行),立即返回 jobId
|
| 工具名 | 用途说明 |
|---|---|
cgw_list_batches |
列出项目内的所有批量工作流 |
cgw_save_batch |
保存批量工作流(校验步骤 ID、前后依赖;支持消费任务输出与 Manifest 命名步骤 outputs 声明) |
cgw_delete_batch |
删除批量工作流 |
cgw_run_batch |
触发执行批量工作流(支持 enqueue: true 排队;排队计划持久化落盘,Daemon 重启自动恢复执行) |
cgw_list_workflows |
列出跨项目工作流模板(workflows/*.json) |
cgw_read_workflow |
读取工作流模板原始 JSON 与解析结构 |
cgw_save_workflow |
新建或更新跨项目工作流模板 |
cgw_delete_workflow |
删除工作流模板 |
cgw_apply_workflow |
实例化应用工作流模板至指定项目(支持动态变量传参及冲突 Diff 预检) |
| 工具名 | 用途说明 |
|---|---|
cgw_list_manifests |
列出所有构建类型及其合法性校验状态与默认产物 |
cgw_manifest_raw |
读取指定构建类型的原始 JSON 定义 |
cgw_save_manifest |
保存构建类型 Manifest(支持命名步骤 outputs 声明,跑完自动校验类型与存在性) |
cgw_delete_manifest |
删除构建类型 Manifest |
cgw_reload_manifests |
触发重读磁盘 manifest/ 目录并报告文件变更 |
cgw_manifest_status |
查看构建类型目录状态及缺失的预设模板 |
cgw_export_manifest |
导出构建类型 JSON 文本内容 |
cgw_detect_manifests |
按宿主机目录结构自动探测匹配的构建类型 |
| 工具名 | 用途说明 |
|---|---|
cgw_list_jobs |
查询最近 50 条 Job 执行记录与状态 |
cgw_job |
查询指定 Job 详情、每一步执行结果与产物信息 |
cgw_job_logs |
获取或流式订阅指定 Job 的实时控制台输出 |
cgw_cancel_job |
协作式取消正在运行或排队中的 Job |
cgw_retry_job |
从失败步骤断点重试或重新开始整个 Job |
cgw_log_days |
查看落盘日志归档日期及保留天数 |
cgw_logs |
按日期、来源(webui/cli/mcp/daemon)及作用域检索历史日志 |
| URI | 资源名称 | 内容说明 |
|---|---|---|
cgw://guide |
使用手册 Playbook | 一页式核心操作指南,包含典型编排流程、错误码对照表与最佳实践 |
cgw://cli |
命令行全量对照 | 机器可读格式的 CLI 命令全量对照表、退出码契约与选项 |
cgw://schema/manifest |
Manifest Schema | 构建类型 Manifest 的 Draft-07 JSON Schema |
cgw://schema/task |
Task Schema | 项目任务的 Draft-07 JSON Schema |
cgw://schema/batch |
Batch Schema | 批量工作流的 Draft-07 JSON Schema |
cgw://schema/client |
Client Schema | 客户机连接请求体的 Draft-07 JSON Schema |
cgw://schema/project |
Project Schema | 项目登记请求体的 Draft-07 JSON Schema |
cgw://schema/workflow |
Workflow Schema | 跨项目工作流模板的 Draft-07 JSON Schema |
-
first-build:首次构建向导 —— 引导 Agent 依次完成客户机测试、环境检测、项目登记、源码推送与首次构建。 -
diagnose-job:任务诊断向导 —— 接收jobId,自动拉取步骤分解与日志输出,分析失败原因并给出修复或重试建议。 -
pick-manifest:构建类型匹配 —— 执行目录特征探测并协助配置工程变量与产物定位。
-
优先阅读
cgw://guide:在编排复杂构建之前先读取 Playbook 掌握项目锁和并发规则。 -
合理处理
409 projectBusy:当项目已有 Job 在运行时,不要高频死循环轮询。使用enqueue: true参与排队,排队计划持久化落盘至queued_runs.json,Daemon 重启自动恢复执行。 -
识别
409 hostBusy:当开启全局hostLock或单机开启hostLock时,多项目共享同一台主机将串行化排队执行;立即请求冲突时返回 409hostBusy。 -
构建前充分预览:在执行大型构建前先调用
cgw_preview_task确认拼接出的 Shell 命令与转义路径。 -
善用断点重试:流水线失败时使用
cgw_retry_job从失败步骤继续,避免浪费时间重复执行已成功的步骤。 -
利用步骤级产物:构建 Manifest 支持在命名步骤中声明
outputs,校验通过后自动发布,后续批量步骤可通过{{steps.<stepId>.outputs.<name>}}消费。
← 首页