ghostlink

GhostLink

AI コーディングエージェントがローカルリポジトリに安全かつ決定論的にアクセスできるようにする、セキュリティを強化した MCP サーバーです。

STDIO に対応する任意の MCP クライアントに追加できます。Claude Code の場合は、対象リポジトリのルートに .mcp.json を作成します。

{
  "mcpServers": {
    "ghostlink": {
      "command": "npx",
      "args": ["-y", "ghostlink"],
      "env": {
        "GHOSTLINK_REPO_ROOT": "/path/to/target/repo"
      }
    }
  }
}

そのディレクトリで claude を実行すると、6 つのリポジトリツールが表示されます。いずれも GHOSTLINK_REPO_ROOT の範囲内に制限されています。すべてのツール呼び出しは、同じ決定論的な ToolEnvelope を返します。

{
  "ok": true,
  "data": { ... },
  "provenance": { "tool": "repo.search", "timestamp": "2026-02-24T...", "duration_ms": 42 }
}

エラー時は、"data" の代わりに "error": { "code": "...", "message": "..." } が返されます。ツールの完全なスキーマについては、docs/TOOLS.md をご覧ください。

ツール

ツール	説明
repo.search	glob フィルタリング、決定論的な並べ替え、出力上限（最大 200 件）に対応した、Ripgrep を利用する正規表現検索です
repo.read_file	サイズ上限（最大 10MB）、バイナリ検出、切り詰めフラグに対応したファイル読み取りです
repo.apply_patch	ドライランモード、完全なサンドボックス検証、失敗時のアトミックなロールバックに対応した統一差分パッチ適用です
repo.run	厳選されたコマンドの実行（test、lint、typecheck、build、smoke）です。任意のシェル実行はできず、許可リストにある引数のみ使用できます
git.status	ブランチ情報、先行／遅延状況の追跡、ファイルエントリの並べ替えに対応した、正規化済みの Git ステータスです
git.diff	パスフィルタリング、サンドボックス検証、出力上限（最大 2MB）に対応した、ステージ済みまたは未ステージの差分です

GhostLink とは？

GhostLink は、Model Context Protocol を利用したローカルファーストのサーバーです。ポリシーで制限された少数のツールを通じて、AI コーディングエージェントにコードベースを公開します。解決するのは、特定の課題です。AI エージェントにはコードの検索、読み取り、パッチ適用、検証が必要ですが、生のシェルアクセスを与えるのはリスクを伴います。GhostLink は、すべてのツール呼び出しを単一のリポジトリルート内に制限し、すべての出力に決定論的な JSON 形式を適用し、すべての呼び出しを監査ログに記録する、サンドボックス化された機能実行環境を提供します。

GhostLink を選ぶ理由

機能	内容
セキュアなローカル開発環境	リポジトリルートのサンドボックス、シェル実行なし、すべてのツール呼び出しの JSONL 監査ログ
決定論的な出力	同じ入力から同じ形式の JSON エンベロープが生成されるため、ゴールデンテストと予測可能なエージェント処理が可能です
ポリシーの適用	コマンドの許可リスト、出力上限、切り詰めフラグ、タイムアウトの適用により、AI による無制限な損害を防ぎます
エージェントループの基盤	自律型コーディングエージェントがループで実行する、検索、読み取り、パッチ適用、検証のサイクルを想定して構築されています
複数サーバーの組み合わせ	リポジトリごとに GhostLink のインスタンスを 1 つ配置し、同じクライアントセッション内の他の MCP サーバーと組み合わせられます
本番運用に対応する Phase 2 の基盤	トランスポート抽象化、スキーマのバージョン管理、認証フックの接続点が、現在のアーキテクチャに保持されています

アーキテクチャ

GhostLink は、コアを変更せずに拡張できるよう設計された 3 層構成です。

flowchart TD
    T["Transport -- src/index.ts<br/>STDIO now, HTTP/SSE in Phase 2"]
    S["Server factory -- src/server.ts<br/>Transport-agnostic tool registration via MCP SDK + Zod schemas"]
    TL["Tools -- src/core/tools/*<br/>Six tools, each returning ToolEnvelope&lt;T&gt;"]
    P["Policy -- src/core/policy/*<br/>Sandbox enforcement, audit logging, output caps"]
    T --> S --> TL --> P

createServer() ファクトリーはトランスポートに依存しません。Phase 2 で HTTP/SSE を追加するには、新しいトランスポートバインディングと認証ミドルウェアを作成するだけです。サーバーファクトリーとすべてのツール実装は変更されません。Phase 3 では、エージェントランタイムが GhostLink を変更するのではなく、その利用者としてメモリーリソースとオーケストレーションを追加します。

クイックスタート

前提条件

• Node.js 18+
• ripgrep（brew install ripgrep）
• 公開する Git リポジトリ

インストール

npm から：

npm install ghostlink

または、ソースから：

git clone https://github.com/bgorzelic/ghostlink.git
cd ghostlink
npm install
npm run build

スモークテスト（生の STDIO）

GhostLink は STDIO 経由で JSON-RPC 2.0 を使用します。次のように直接テストできます。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  GHOSTLINK_REPO_ROOT=/path/to/target/repo node dist/index.js

すべての 6 つのツールとそのスキーマが返されます。

クライアントの設定

GhostLink は、STDIO トランスポートをサポートするあらゆる MCP クライアントで動作します。このページの上部にある npx のスニペットはどこでも使えます。ソースをチェックアウトした場合は、ビルド済みのエントリーポイントを node で実行します。

{
  "ghostlink": {
    "command": "node",
    "args": ["/absolute/path/to/ghostlink/dist/index.js"],
    "env": {
      "GHOSTLINK_REPO_ROOT": "/path/to/target/repo"
    }
  }
}

クライアント	設定場所
Claude Code	対象リポジトリのルートにある .mcp.json（mcpServers キー）。その後、そこで claude を実行します
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json（mcpServers キー）。その後、再起動します
Cursor、Windsurf、Cline など	クライアントの MCP サーバー設定。ファイルの場所については、各クライアントのドキュメントを参照してください

トランスポートは常に STDIO です。対象プロジェクト用のすぐに使える .mcp.json と CLAUDE.md のテンプレートは、templates/ にあります。

セキュリティモデル

GhostLink は、あらゆる層で多層防御を徹底しています。

• リポジトリルートのサンドボックス — すべてのファイル操作は GHOSTLINK_REPO_ROOT 内に制限されます。パストラバーサル、シンボリックリンクによる脱出、ヌルバイト、ルート外の絶対パスは、ファイルシステムにアクセスする前にすべて拒否されます。
• シェル実行なし — repo.run は shell: false で spawn を使用します。コマンドは固定の許可リスト（test、lint、typecheck、build、smoke）に限定され、コマンドごとに引数の許可リストが設定されています。環境変数は安全な 6 つの変数のみに制限されます。
• 出力上限 — 大量のデータを返す各ツールには、厳格な上限（検索結果 200 件、ファイル読み込み 10MB、stdout/stderr 200KB、差分 2MB）が設定されています。切り詰めが発生した場合は必ず示され、通知なしに行われることはありません。
• アトミックなパッチのロールバック — repo.apply_patch は、書き込み前にすべてのパスを検証し、すべてのパッチを計算します。書き込みが失敗した場合、完了済みの書き込みは元の状態にロールバックされます。
• タイムアウトの適用 — repo.run は設定可能なタイムアウト（デフォルト 120s、上限 300s）に達すると、まず SIGTERM、次に SIGKILL を送ってプロセスを終了します。

脅威モデルと対策の全文：docs/SECURITY.md。

監査ログ

すべてのツール呼び出しで、JSONL 形式の監査エントリーが生成されます：{ts, tool, ok, duration_ms, error_code?, repo_root}。

GHOSTLINK_LOG	動作
stdout（デフォルト）	JSONL 形式の監査行を stderr に出力します
file	JSONL を logs/ghostlink.jsonl に書き込みます（10MB で自動ローテーション）
off	ログを記録しません

環境変数で設定します。

GHOSTLINK_LOG=file GHOSTLINK_REPO_ROOT=/path/to/repo node dist/index.js

プロンプトテンプレート

docs/PROMPTS.md には、高い自律性を持つエージェント運用ですぐに使えるプロンプトが用意されています。オーケストレーター用プロンプト、サブエージェントの役割定義（Protocol Engineer、Toolsmith、Security Reviewer、Test Engineer、Docs Engineer）、複数インスタンスの連携パターンが含まれます。

開発

npm install          # Install dependencies
npm test             # Run test suite (108 tests via Vitest)
npm run lint         # ESLint
npm run typecheck    # TypeScript strict mode check
npm run build        # Compile to dist/
npm run dev          # Dev mode with auto-reload (tsx watch)

編集後の完全な検証：

npm test && npm run lint && npm run typecheck && npm run build

ドキュメント

ドキュメント	説明
docs/TOOLS.md	正式なツールスキーマ（バージョン管理された公開 API）
docs/SECURITY.md	脅威モデルと対策
docs/QUICKSTART.md	セットアップ、スモークテスト、クライアント設定の手順
docs/INSPECTOR.md	MCP Inspector による手動テストガイド
docs/PROMPTS.md	オーケストレーションとサブエージェントの役割向けプロンプト
docs/ROADMAP_DETAILED.md	Phase 2 と Phase 3 の成果物を含む、製品ロードマップの全容
docs/WHY_GHOSTLINK.md	戦略的な価値提案とアーキテクチャの根拠
docs/ENGINEERING_REPORT_v0.1.0.md	マイルストーンの履歴と意思決定ログを含む v0.1.0 のリリース報告
templates/	対象プロジェクト用のすぐに使える CLAUDE.md と .mcp.json のテンプレート

ロードマップ

Phase 1 -- ローカル STDIO［リリース済み、v0.1.0］

決定論的なツールインターフェース、リポジトリルートのサンドボックス、厳選されたコマンド実行、108 件のテスト、JSONL 監査ログ、npm パッケージを公開済み。

フェーズ 2 -- リモートトランスポート［計画中］

HTTP/SSE トランスポート、OAuth 2.1 認証、マルチユーザーテナントの分離、テナントごとのレート制限、スキーマのバージョン管理、相関 ID を含む構造化監査ログ。

フェーズ 3 -- エージェントランタイム［将来］

MCP 経由で公開される永続メモリーリソース、オプションのポリシーで制御されたメモリー書き込みツール、オーケストレーションレイヤー（GhostLink の外部）、評価ループ、サブエージェント調整フレームワーク。

ライセンス

ISC