gctrl

Ground Control（GCTRL）MCP 服务

将 Ground Control 的知识管理功能封装为 MCP 工具，供 Claude 和其他 AI Agent 使用。

可用工具

工具	描述
gctrl_extract	从文本中提取知识 → Neo4j 实体 + Qdrant 向量
gctrl_query	针对知识图谱提问（混合 RAG）
gctrl_search_entities	按名称/类型搜索特定实体
gctrl_list_graphs	列出所有知识图谱编译结果
gctrl_fuse	将提取任务合并为统一图谱
gctrl_list_ontologies	列出可用本体
gctrl_list_extractions	列出最近的提取任务
gctrl_store	存储知识（类似 Obsidian 笔记，但会提取知识图谱）
gctrl_schema	获取知识图谱架构
gctrl_code_index	将本地仓库索引到代码库知识库（编译类型为 CODE）。仅限直接模式（它会索引此机器，因此网关无法提供此工具），且需要可选的 gctrl-code-indexer 软件包——若未安装，该工具会返回安装提示，其他所有工具仍可正常使用。
gctrl_code_symbol	按名称/路径/正则表达式查找代码符号（通过 HTTP 网关代理）
gctrl_code_trace	跟踪符号的调用方/被调用方（通过 HTTP 网关代理）
gctrl_code_impact	分析已更改符号/文件的影响（通过 HTTP 网关代理）
gctrl_code_architecture	查看代码库知识库的语言、热点和社群（通过 HTTP 网关代理）

已弃用名称（别名，将在 v2 中移除）

为兼容现有 .mcp.json 配置，上方每个工具也提供对应的旧名称。 每次调用别名时，都会向 stderr 记录弃用警告，且将在 v2.0 中移除——请迁移。

已弃用的别名	请改用
borghive_extract	gctrl_extract
borghive_query	gctrl_query
borghive_store	gctrl_store
borghive_fuse	gctrl_fuse
borghive_search_entities	gctrl_search_entities
borghive_list_graphs	gctrl_list_graphs
borghive_list_ontologies	gctrl_list_ontologies
borghive_list_extractions	gctrl_list_extractions
borghive_schema	gctrl_schema

快速入门（npm）

该软件包已发布到 npm，名称为 gctrl-mcp，也已收录在官方 MCP Registry 中，名称为 io.github.GCTRL-TECH/gctrl。将其添加到 MCP 客户端配置中 （Claude Code、Claude Desktop、Cursor、Codex 等）：

{
  "mcpServers": {
    "gctrl": {
      "command": "npx",
      "args": ["-y", "gctrl-mcp"],
      "env": {
        "GCTRL_GATEWAY_URL": "http://localhost:4000/api/agent/mcp",
        "GCTRL_API_TOKEN": "gctrl_..."
      }
    }
  }
}

需要正在运行的 GCTRL harness（开始使用）。

使用 GCTRL 编码（推荐用于编码 Agent）

在网关入口旁以直接模式运行服务，让 Agent 使用本地代码工具，并由它自行维护仓库的代码库知识库：

{
  "mcpServers": {
    "gctrl":      { "command": "npx", "args": ["-y", "gctrl-mcp"],
                    "env": { "GCTRL_GATEWAY_URL": "https://<host>/api/agent/mcp", "GCTRL_API_TOKEN": "gctrl_..." } },
    "gctrl-code": { "command": "npx", "args": ["-y", "gctrl-mcp"],
                    "env": { "GCTRL_API_URL": "https://<host>/api", "GCTRL_API_TOKEN": "gctrl_...",
                             "GCTRL_MCP_TOOLS": "code", "GCTRL_CODE_AUTO_INDEX": "cwd" } }
  }
}

设置 GCTRL_CODE_AUTO_INDEX=cwd 后，服务会在启动后立即索引 MCP 客户端启动时所在的目录（增量索引——已预热的仓库只需数秒），这样 Agent 首次调用 gctrl_code_symbol 时就能查询最新图谱。服务的指令中包含所有已连接 Agent 都必须遵循的编码协议：每个会话索引一次；在读取文件之前，通过 gctrl_code_symbol / gctrl_code_trace / gctrl_code_architecture 进行导航；更改符号之前运行 gctrl_code_impact；进行较大修改后重新索引；通过 gctrl_query 询问原因，并使用 gctrl_store 将决策存储在相关符号旁。根据对 GCTRL 自身仓库的测量，通过图谱回答结构类问题所用的令牌比 grep-and-read 少 95.6%。

Configuration

Env var	Purpose
GCTRL_GATEWAY_URL	推荐：你的 harness 的 MCP 网关 URL（http://<host>:4000/api/agent/mcp）。stdio 服务充当轻量级的身份验证代理。
GCTRL_API_URL	替代直连模式：GCTRL API 基础 URL（http://<host>:4000/api）；工具在本地直接调用 API。
GCTRL_API_TOKEN	范围受限的 GCTRL Access Token（gctrl_…），可在 Settings → Access Control 中创建，并设置 clearance level 和各图的授权。遵循最小权限原则——Agent 只能看到此令牌获准访问的内容。
GCTRL_MCP_TOOLS	可选的工具集筛选器。设为 code 可仅注册本地代码工具（gctrl_code_index、gctrl_code_symbol、gctrl_code_trace、gctrl_code_impact、gctrl_code_architecture）——用于 Anvil/Hermes 的 gctrl-code stdio 条目，与 HTTP 网关的 gctrl/gctrl-projekt 条目分开。仅适用于直连模式：在网关模式下，网关自身的工具列表会原样代理，因此此筛选器不起作用，服务启动时会说明这一点。

| GCTRL_CODE_AUTO_INDEX | 直连模式：cwd（或仓库路径）会在启动后立即于后台为该仓库编制索引——增量执行，不会导致启动失败。让 Codebase KB 自动运行，而不再依赖人工记得操作。 | | GCTRL_CODE_COMPILATION_ID | 直连模式：当 Agent 未传入 compilationId 时，gctrl_code_index 使用的 CODE compilation（一个项目 = 一个仓库 = 一个代码图）。如果 Agent 显式传入 compilationId，则优先使用该值。 | | GCTRL_CODE_FOLDER | 直连模式：代码图的文件夹路径（Users/<name>/Code），服务会在此创建 <repo> (code)。按用户启动服务的宿主（Anvil）应设置此项，让每位同事的代码存入各自的文件夹；否则 GCTRL 会将文件存入账户所有者的 Users/<owner>/Code。 |

仅供开发使用的备用方案：GCTRL_EMAIL + GCTRL_PASSWORD（具有完整 clearance 的 JWT）。请勿在生产环境中使用。

从源代码构建

cd borghive/services/mcp
npm install
npm run build

开发代码索引器

gctrl-code-indexer 是一个可选依赖，目前尚未发布到 npm，因此在此处执行普通的 npm install 不会安装它。要针对仓库内的软件包开发或测试 gctrl_code_index，请先链接一次：

cd borghive/packages/code-indexer && npm ci && npm run build
cd ../../services/mcp && npm install ../../packages/code-indexer --no-save
# or: npm link ../../packages/code-indexer

服务为索引器声明了本地类型，因此无论是否安装该软件包，npm run build 都能成功——区别仅在于 gctrl_code_index 是能在运行时正常工作，还是会返回安装提示。

发布顺序

gctrl-mcp 和 gctrl-code-indexer 是两个 npm 软件包，必须按以下顺序发布：

1. 发布 [email protected]。
2. 将 services/mcp/package.json 中的 optionalDependencies 改为真实的 registry 版本范围 （目前已是 ^0.1.0；请确认能够解析），然后重新运行 npm install。
3. 将 gctrl-mcp 升级到 1.1.0（更新 package.json 和根目录下的 package-lock.json）。
4. 发布 gctrl-mcp。

如果在索引器发布到 npm 之前就升级 gctrl-mcp，会导致所有现有用户的 npx gctrl-mcp 无法使用——这正是版本目前停留在 1.0.1 的原因。