x402-codesearch-mcp

x402-codesearch-mcp

リポジトリのファイルをチャンク化して埋め込み、無料でライブのセマンティックコード検索 Worker にインデックス登録する、無料の MCP（Model Context Protocol）サーバーです。MCP ツール index_code を 1 つ提供します。

有料の x402 ゲート付き HTTP API のオープンな導線となる双子です。

x402-codesearch-poc.theliminalguy.workers.dev — インデックス登録済みのリポジトリを対象に実際のセマンティック検索を行う POST /search。クエリごとに Base 上で $0.01 USDC が必要です。x402 payment protocol を使用します。

他の無料の双子と何が違うのか（まずはこちらをお読みください）

x402-repohealth-mcp のような姉妹パッケージは、有料 Worker のロジックをローカルで完全に再実装し（純粋関数で、外部アカウントに依存しません）、機能全体を MCP 経由で無料で提供します。

このパッケージではそれができません。有料 Worker のセマンティック検索は、無料・ローカル・ポータブルな代替手段がない、Cloudflare アカウントに紐づいた 2 つのバインディングに依存しています。

• Workers AI（@cf/baai/bge-base-en-v1.5）— 埋め込みを生成します
• Vectorize — 埋め込みを保存し、コサイン類似度で検索します

どちらも Worker 自身の Cloudflare アカウント内でしか利用できません。そのアカウントの外で無料実行する方法はないため、この MCP サーバーはそれらを偽装したりプロキシしたりしません。

実際に無料で利用できるのは、ライブ Worker 自体の POST /index です。ファイルをチャンク化して埋め込み、Worker 自身の Vectorize インデックスに追加する処理です。このパッケージが MCP ツールとして公開する、実際に無料でステートレスな機能はこれだけです。対応する POST /search は、これまでどおりライブ Worker に直接送信する、実際の x402 ゲート付き HTTP 呼び出しです。

機能

ツールは index_code の 1 つです。

• 入力：{ repoId: string, files: [{ path: string, content: string }] }
• 正確に同じ本文を指定して POST https://x402-codesearch-poc.theliminalguy.workers.dev/index を呼び出します（無料、支払い不要）。
• 出力：{ repoId, filesIndexed, chunksIndexed } と、インデックス登録したデータの検索には有料エンドポイントが必要であることを呼び出し元に伝える note フィールドです。

search_code ツールは公開しません。このツールでインデックス登録したデータのセマンティック検索には、x402 ゲート付きエンドポイントを直接呼び出す必要があります。

POST https://x402-codesearch-poc.theliminalguy.workers.dev/search
Body: { "repoId": "...", "query": "..." }
Price: $0.01 USDC on Base, via the x402 protocol (e.g. x402-fetch / x402-axios)

/search への未払いのリクエストは、実際の x402 支払い手順を含む 402 Payment Required を返します。

インストールと実行

npx x402-codesearch-mcp

または、MCP クライアントの設定に追加します（例：Claude Desktop の claude_desktop_config.json）。

{
  "mcpServers": {
    "codesearch": {
      "command": "npx",
      "args": ["-y", "x402-codesearch-mcp"]
    }
  }
}

ツール：index_code

入力：

{
  "repoId": "my-repo",
  "files": [
    { "path": "src/retry.py", "content": "def retry_with_backoff(...): ..." }
  ]
}

出力（MCP ツールのテキストコンテンツ、JSON 文字列化）：

{
  "repoId": "my-repo",
  "filesIndexed": 1,
  "chunksIndexed": 2,
  "note": "Indexing succeeded (free). To semantically search this repoId, call the x402-gated POST https://x402-codesearch-poc.theliminalguy.workers.dev/search directly ($0.01 USDC on Base per query) — not available through this free MCP tool."
}

ローカル開発

npm install
npm run dev              # runs src/index.ts directly on stdio via tsx
npm run build             # compiles to dist/ for the published npm package
npm run test:index        # calls indexCode() directly against the real live Worker, no MCP transport

src/client.ts と src/types.ts には、ライブ Worker の /index エンドポイントに対する簡易 HTTP クライアントがあります。src/index.ts は indexCode() を呼び出す簡易 MCP ラッパーです。

実際の機能と制限

• 実際の機能： このツールが呼び出す POST /index は実際のライブ Worker に送信され、Worker は指定されたファイルを実際にチャンク化し、Workers AI を実際に呼び出して埋め込みを生成し、Vectorize に実際に追加します。ここでモックやハードコードは使っていません。ライブ Worker に対するエンドツーエンドの検証済みです（下記参照）。
• 本当に無料： POST /index は支払いも API キーも不要です。ドキュメント上だけでなく、ライブ環境で確認済みです。
• 無料ではなく、意図的にここでは公開していない機能： 同じ Worker の POST /search です。これは見落としではなく、意図的に範囲を限定しています。上記の「他の無料の双子と何が違うのか」を参照してください。
• ローカルキャッシュ／重複排除なし： index_code を呼び出すたびにライブ Worker へ POST します。同じファイルを再度インデックス登録すると、チャンク化・埋め込み生成・追加が再実行されます。

有料の HTTP ツインを直接使用する場合

次の場合は、この MCP サーバーに加えて、または代わりに、稼働中の Worker に対して POST /search を使用してください。

• index_code でリポジトリのインデックスを作成し、セマンティック検索を実際に行いたい場合。
• エージェントがすでに x402（例：x402-fetch／x402-axios 経由）に対応しており、クエリごとに Base 上で $0.01 USDC を支払える場合。
• 本番環境での検索や大量検索が必要な場合。この MCP サーバーの index_code ツールは、ほかのすべての呼び出し元と同じ無料の /index エンドポイントを共有しますが、/search は呼び出し元にかかわらず、呼び出しごとに課金されます。

ライセンス

MIT