Context Repo Mcp Server

Context Repo MCP stdio ブリッジ

context-repo-mcp は、ホスト型の Context Repo MCP 用の、ステートレスでネットワーク接続を必要とするトランスポートアダプターです。ローカルの stdio コマンドまたは API キー認証を必要とする MCP クライアントから、ホスト型サービスを利用できるようにします。

stdio MCP client
  -> context-repo-mcp
  -> HTTPS POST https://contextrepo.com/mcp
  -> hosted Context Repo MCP

このパッケージは、Context Repo のツールをローカルで実装または登録しません。ツール、プロンプト、リソース、スキーマ、ビジネス動作、エラー、結果の形式はホスト型 MCP が管理します。このブリッジは stdio メッセージをフレーミングし、リクエストを認証し、ホスト型サーバーからの応答を検証したうえで、受け入れた JSON-RPC 応答テキストを再シリアライズせずに中継します。

適切な接続方法を選ぶ

OAuth を使ったリモート MCP

クライアントがリモート MCP サーバーと OAuth に対応している場合は、ホスト型 MCP に直接接続してください。

{
  "mcpServers": {
    "context-repo": {
      "url": "https://contextrepo.com/mcp"
    }
  }
}

クライアントの設定場所とプロパティ名は異なる場合があります。この汎用例を調整する際は、MCP クライアントのドキュメントを参照してください。

npm ブリッジは OAuth を実装せず、ブラウザーを開いたり、OAuth トークンを保存したり、コールバックポートを公開したりしません。

API キーを使ったローカル stdio

クライアントでローカルコマンドまたは API キーの設定が必要な場合は、npm ブリッジを起動してください。

{
  "mcpServers": {
    "context-repo": {
      "command": "npx",
      "args": ["-y", "context-repo-mcp"],
      "env": {
        "CONTEXTREPO_API_KEY": "gm_your_api_key"
      }
    }
  }
}

Context Repo の設定で API キーを生成してください。MCP クライアントのシークレットまたは環境設定に保存してください。ソース管理にコミットしないでください。

CONTEXTREPO_API_KEY が正式な環境変数です。その値は gm_ で始まる空でない文字列である必要があります。

CONTEXT_REPO_API_KEY は非推奨の互換性エイリアスとして引き続き利用でき、stderr に警告を 1 回出力します。両方の名前が設定されている場合、値は一致している必要があります。両方の値が存在する場合も、エイリアスの非推奨警告が出力されます。

要件

• Node.js 18 以降
• 設定されたホスト型 MCP エンドポイントへのネットワークアクセス
• npm/stdio 接続経路用の Context Repo API キー

インストール

MCP クライアントでは、パッケージをインストールせずに実行できます。

npx -y context-repo-mcp

または、グローバルにインストールします。

npm install --global context-repo-mcp
context-repo-mcp

このコマンドは通常、MCP クライアントによって起動・制御されます。対話型シェルインターフェイスを提供するのではなく、stdin から JSON-RPC メッセージを読み取り、stdout に応答を書き込みます。

エージェントスキル

このリポジトリでは、互換性のあるエージェントに Context Repo をいつ、どのように使うかを教える、再利用可能なガイダンス SKILL.md も配布しています。以下の内容を扱います。

• プロンプト、ドキュメント、コレクションを対象とした項目単位の検索。
• ドキュメントコンテンツ内の階層的な検索とナビゲーション。
• reason を用いた、保存済みドキュメントに基づく引用付きのベストエフォート回答。
• 必須の expectedRevision を使った、リビジョンの安全性を考慮したドキュメントの更新と復元。
• OAuth による直接接続と、API キーを使う stdio ブリッジの違い。

このスキルは、Skills CLI によってこの GitHub リポジトリからインストールされます。npm パッケージには含まれておらず、npx context-repo-mcp を実行してもインストールされません。

対応エージェント向けにスキルをグローバルにインストールします。

npx skills add Gitmaxd/context-repo-mcp --global

スキルの変更がマージされた後、既存のインストールを更新します。

npx skills update context-repo-mcp

スキルをインストールしても、MCP クライアントへの接続や認証情報の提供は行われず、それだけでツールが追加されることもありません。上記の説明に従って、ホスト型サービスへの直接接続または stdio ブリッジを別途設定してください。更新したスキルがまだ表示されない場合は、新しいエージェントセッションを開始してください。

機能の管理と検出

npm パッケージには、意図的に静的なツール一覧が含まれていません。MCP の初期化後、tools/list、prompts/list、resources/list など、プロトコルの一覧取得メソッドを使用して、ホスト型サーバーが現在提供している機能を検出してください。

ホスト型の機能とビジネス動作は、npm パッケージの新しいリリースなしに変更されることがあります。このパッケージのバージョンを固定しても固定されるのはブリッジの実装であり、ホスト型のツール群ではありません。

実行時の契約

入力のフレーミングとディスパッチ

• 標準入力は UTF-8 で、空でない各行に JSON-RPC ペイロードが 1 つ含まれます。
• LF と CRLF の行末を受け付けます。最終行に末尾の改行は不要です。
• 空行は無視されます。
• 不正な JSON があると、コード -32700 と id: null を含むローカルの JSON-RPC パースエラーが発生します。後続の入力行の処理は続行されます。
• 正常にパースされた行は、それぞれ個別にディスパッチされます。複数のリクエストが同時に処理中になることがあるため、レスポンスは入力順と異なる順序で届く場合があり、JSON-RPC ID と照合する必要があります。
• 標準入力が正常に EOF に達すると、プロセスは処理中のすべてのリクエストが完了するまで待機します。

ホスト側へのリクエスト

正常にパースされた各入力行は、次の内容を付けて、設定済みの MCP エンドポイントへの HTTP POST の本文として 1 回だけ送信されます。

Authorization: API-Key <configured key>
Content-Type: application/json
Accept: application/json
User-Agent: context-repo-mcp

ブリッジは、reason ツールの呼び出しには 90 秒、その他のホスト側レスポンスには 30 秒のタイムアウトを適用します。リダイレクトには追従せず、失敗した POST リクエストを再試行しません。

ホスト側レスポンスの検証

空でないホスト側レスポンスは、以下のすべての条件を満たす場合にのみ受け付けられます。

• メディアタイプが application/json または application/*+json 型である。
• 本文が 1 行で、リテラルのキャリッジリターンまたは改行を含まない。
• 本文が JSON-RPC 2.0 のレスポンスオブジェクト、または有効な JSON-RPC 2.0 レスポンスオブジェクトからなる空でないバッチとしてパースできる。
• 各レスポンスの ID が文字列、数値、または null であり、result または error のいずれか一方だけを含む。エラーオブジェクトには、整数の code と文字列の message が必要です。

HTTP ステータスだけで成功かどうかは決まりません。有効な JSON-RPC の結果またはエラーは、HTTP ステータスが 2xx 以外であっても中継されます。

検証後、元のホスト側レスポンスのテキストを再シリアライズせずに標準出力へ書き込みます。ブリッジが追加するのは、標準入出力の行プロトコルに必要な終端の LF のみです。これにより、content、structuredContent、_meta、数値テキスト、エスケープ、空白、将来追加される未知のフィールドなどが保持されます。

空の成功レスポンスは、JSON-RPC 通知（id のないオブジェクト）の場合にのみ受け付けられます。この場合、標準出力には何も出力されません。

ブリッジの障害

タイムアウト、リダイレクト、ネットワーク障害、空のリクエストレスポンス、未対応のコンテンツタイプ、SSE、複数行の本文、不正な JSON、有効でない JSON-RPC レスポンスは、すべてフェイルクローズで処理されます。

• リクエストの場合、ブリッジは元の有効な ID（または null）、コード -32000、および次の固定メッセージを含む JSON-RPC エラーを 1 つ書き込みます。 Context Repo bridge could not reach the hosted MCP server
• 通知の場合、ブリッジは JSON-RPC レスポンスを書き込まず、同じ固定メッセージを標準エラー出力に出力します。
• 生のネットワークエラー、上流の本文、認証情報、ペイロード、スタックトレース、ローカルのファイルシステムパスは、これらの診断情報に含めません。

標準出力には JSON-RPC のみが出力されます。設定に関する警告と障害診断は標準エラー出力に送られます。

開発用エンドポイントの上書き

CONTEXTREPO_MCP_URL は、開発およびテスト時に https://contextrepo.com/mcp を上書きします。値には絶対 URL を指定する必要があります。

• ループバック以外のホストでは HTTPS が必要です。
• 平文 HTTP が許可されるのは、localhost、127.0.0.1、または [::1] のみです。
• URL に埋め込まれたユーザー名、パスワード、フラグメントは拒否されます。

ブリッジは設定された API キーをこのエンドポイントに送信します。自分が管理し、信頼できる上書き先のみを使用してください。エンドポイントが本番の Context Repo サービスではない場合は、使い捨てのテストキーを使用してください。

削除された v2 の変数 CONTEXTREPO_API_URL は REST API を指すものであり、このブリッジではサポートされていません。

トラブルシューティング

プロセスがすぐに終了する

ブリッジは標準入力を読み取る前に設定を検証します。CONTEXTREPO_API_KEY が設定されていて、gm_ で始まり、非推奨のエイリアスと競合していないことを確認してください。

クライアントにブリッジ障害が表示される

安定したブリッジ障害メッセージでは、上流の詳細情報が意図的に非表示になります。 ネットワーク障害、タイムアウト、リダイレクト、空のリクエスト応答、 未対応のコンテンツタイプ、複数行または不正な形式の本文、無効な JSON-RPC 応答が原因である可能性があります。

認証エラーやビジネスエラーを含む、有効なホスト型 JSON-RPC エラーは 変更せずに中継されます。ホスト型 MCP からエラーが返された場合は、その内容に 従ってください。

ホスト型呼び出しを利用できない場合は、Context Repo のステータスを確認してください。 このパッケージには、ローカルまたはオフラインでのフォールバックはありません。

クライアントに非推奨の警告が表示される

CONTEXT_REPO_API_KEY を CONTEXTREPO_API_KEY に置き換えてください。両方の変数が 環境から引き継がれている場合は、正式な変数が設定されていることを確認してから、 非推奨の別名を削除してください。

開発

npm ci
npm test
npm ls --all
npm pack --dry-run

このプロジェクトでは ES モジュールと組み込みの node:test ランナーを使用しています。実行時依存関係も 開発依存関係もありません。自動テストでは、注入された fetch 実装またはループバック HTTP サーバーを使用するため、実際の API キーは必要なく、 contextrepo.com への接続も行いません。

ソースの構成：

• src/config.js は環境設定を検証します。
• src/index.js は stdio 入力をフレーミングし、処理を振り分け、出力を書き込みます。
• src/bridge.js はホスト型リクエストをそれぞれ送信し、その応答を検証します。
• test/ は設定、トランスポート、プロセスの動作、パッケージ化された npm 成果物をテストします。

v2 からの移行

バージョン 3 では、重複していたローカル MCP 実装をこのホスト型 stdio ブリッジに置き換えました。そのため、ネットワークアクセスが必要となり、MCP の機能は ホスト型サーバーから提供されます。

• CONTEXT_REPO_API_KEY を CONTEXTREPO_API_KEY に変更します。
• 削除された REST オーバーライド CONTEXTREPO_API_URL は、開発またはテストの場合に限り、 CONTEXTREPO_MCP_URL に置き換えます。
• MCP クライアントが対応している場合は、ホストへの直接 OAuth 接続を優先してください。

移行中、一時的に v2 に戻す必要がある場合は、最後の v2 リリースを 明示的に固定してください。

npx -y [email protected]

リンク

• Context Repo
• Context Repo MCP ドキュメント
• npm パッケージ
• サービスのステータス
• Model Context Protocol
• GitHub リポジトリ
• 課題トラッカー
• サポート

ライセンス

MIT。詳細は LICENSE を参照してください。