gctrl

Ground Control（GCTRL）MCP サーバー

Ground Control のナレッジ管理機能を MCP ツールとして公開し、Claude やその他の AI エージェントから利用できるようにします。

利用可能なツール

ツール	説明
gctrl_extract	テキストからナレッジを抽出します → Neo4j のエンティティと Qdrant のベクトル
gctrl_query	ナレッジグラフについて質問します（ハイブリッド RAG）
gctrl_search_entities	名前／タイプを指定して特定のエンティティを検索します
gctrl_list_graphs	すべてのナレッジグラフのコンパイルを一覧表示します
gctrl_fuse	抽出ジョブを統合グラフにマージします
gctrl_list_ontologies	利用可能なオントロジーを一覧表示します
gctrl_list_extractions	最近の抽出ジョブを一覧表示します
gctrl_store	ナレッジを保存します（Obsidian のノートに似ていますが、KG 抽出機能があります）
gctrl_schema	ナレッジグラフのスキーマを取得します
gctrl_code_index	ローカルリポジトリを Codebase KB にインデックス化します（コンパイルタイプは CODE）。ダイレクトモードでのみ利用できます（このマシンをインデックス化するため、ゲートウェイからは提供できません）。また、オプションの gctrl-code-indexer パッケージが必要です。これがない場合、ツールはインストール方法を案内し、その他のツールはすべて引き続き動作します。
gctrl_code_symbol	名前／パス／正規表現でコードシンボルを検索します（HTTP ゲートウェイ経由でプロキシされます）
gctrl_code_trace	シンボルの呼び出し元／呼び出し先を追跡します（HTTP ゲートウェイ経由でプロキシされます）
gctrl_code_impact	変更されたシンボル／ファイルの影響を分析します（HTTP ゲートウェイ経由でプロキシされます）
gctrl_code_architecture	Codebase KB の言語、ホットスポット、コミュニティを表示します（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 ハーネスの実行が必要です（利用開始）。

GCTRL を使ったコーディング（コーディングエージェントに推奨）

ゲートウェイのエントリの隣でサーバーをダイレクトモードで実行すると、エージェントがローカルコードツールを利用でき、リポジトリの Codebase KB も自動で最新の状態に保たれます。

{
  "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 クライアントが起動されたディレクトリをインデックス化します（差分インデックス化のため、すでに処理済みのリポジトリなら数秒で完了します）。これにより、エージェントが初めて gctrl_code_symbol を呼び出す時点で、グラフは最新の状態になっています。サーバーの指示には、接続されたすべてのエージェントが従うコーディングプロトコルが含まれています。セッションごとに一度インデックス化し、ファイルを読む前に gctrl_code_symbol／gctrl_code_trace／gctrl_code_architecture で調査し、シンボルを変更する前に gctrl_code_impact を実行し、大規模な編集の後には再インデックス化し、変更理由について gctrl_query に質問して、判断内容を gctrl_store でシンボルの近くに保存します。GCTRL 自身のリポジトリでの測定では、グラフを使って構造に関する質問に回答すると、grep で検索してファイルを読む場合と比べてトークン数を 95.6 % 削減できました。

設定

環境変数	用途
GCTRL_GATEWAY_URL	推奨：ハーネスの MCP ゲートウェイの URL（http://<host>:4000/api/agent/mcp）。stdio サーバーは、認証済みの軽量なプロキシとして動作します。
GCTRL_API_URL	代替の直接モード：GCTRL API のベース URL（http://<host>:4000/api）。ツールは API に対してローカルで実行されます。
GCTRL_API_TOKEN	スコープ付き GCTRL アクセストークン（gctrl_…）。設定 → アクセス制御でクリアランスレベルとグラフごとの許可を指定して作成します。最小権限の原則により、エージェントに表示されるのはトークンで許可された範囲のみです。
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（またはリポジトリのパス）を指定すると、起動直後にそのリポジトリをバックグラウンドでインデックス化します。増分処理で、致命的なエラーにはなりません。習慣に頼らず、コードベースの KB を自動化できます。 | | GCTRL_CODE_COMPILATION_ID | 直接モード：エージェントが指定しなかった場合に gctrl_code_index が使用する CODE コンパイル ID です（1 つのプロジェクト＝1 つのリポジトリ＝1 つのコードグラフ）。エージェントが明示的に指定した compilationId が優先されます。 | | GCTRL_CODE_FOLDER | 直接モード：サーバーが <repo> (code) として自動作成するコードグラフ用のフォルダーパス（Users/<name>/Code）です。ユーザーごとにサーバーを起動するホスト（Anvil）では、この変数を設定すると、同僚それぞれのコードが各自のフォルダーに保存されます。設定しない場合、GCTRL のファイルはアカウント所有者の Users/<owner>/Code に保存されます。 |

開発専用のフォールバック：GCTRL_EMAIL + GCTRL_PASSWORD（フルクリアランスの 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 は 2 つの npm パッケージであり、次の順序で公開する必要があります。

1. [email protected] を公開します。
2. services/mcp/package.json の optionalDependencies を実際のレジストリのバージョン範囲に切り替えます （現在は ^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 のままです。