io.github.liminalpepe/x402-codesearch-mcp

x402-codesearch-mcp

A free MCP (Model Context Protocol) server that indexes a repo's files — chunked and embedded — into the live semantic code search Worker, for free, via one MCP tool: index_code.

This is the open funnel twin of a paid, x402-gated HTTP API:

x402-codesearch-poc.theliminalguy.workers.dev — POST /search, $0.01 USDC on Base per query via the x402 payment protocol, for the actual semantic search step over an indexed repo.

Why this one is different from the other free twins (read this first)

Sibling packages like x402-repohealth-mcp fully reimplement their paid Worker's logic locally (pure functions, no external account-bound dependency) and expose the entire feature for free via MCP.

This package cannot do that. The paid Worker's semantic search depends on two Cloudflare-account-bound bindings with no free, local, or portable equivalent:

• Workers AI (@cf/baai/bge-base-en-v1.5) — generates the embeddings
• Vectorize — stores and queries those embeddings by cosine similarity

Both only exist inside the Worker's own Cloudflare account. There is no way to run them for free outside that account, so this MCP server does not try to fake or proxy them.

What genuinely is free is POST /index on the live Worker itself — the step that chunks a file, embeds it, and upserts it into that Worker's own Vectorize index. That's the one real, free, stateless capability this package exposes as an MCP tool. The matching POST /search step stays exactly where it already is: a real x402-gated HTTP call directly against the live Worker.

What it does

One tool, index_code:

• Input: { repoId: string, files: [{ path: string, content: string }] }
• Calls POST https://x402-codesearch-poc.theliminalguy.workers.dev/index (free, no payment) with that exact body.
• Output: { repoId, filesIndexed, chunksIndexed } plus a note field reminding the caller that searching what was just indexed requires the paid endpoint.

It does not expose a search_code tool. Semantic search over data indexed with this tool requires calling the x402-gated endpoint directly:

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)

An unpaid request to /search returns 402 Payment Required with real x402 payment instructions.

Install & run

npx x402-codesearch-mcp

Or add it to an MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

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

Tool: index_code

Input:

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

Output (MCP tool text content, JSON-stringified):

{
  "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."
}

Local development

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 and src/types.ts hold the thin HTTP client against the live Worker's /index endpoint — src/index.ts is a thin MCP wrapper around indexCode().

What's real vs. limited

• Real: the POST /index call this tool makes goes to the actual live Worker, which really chunks the given files, really calls Workers AI for embeddings, and really upserts into Vectorize — nothing here is mocked or hardcoded. Verified end-to-end against the live Worker (see below).
• Genuinely free: POST /index requires no payment and no API key — confirmed live, not just documented.
• Not free, and not exposed here by design: POST /search on the same Worker. That's a deliberate scope boundary, not an oversight — see "Why this one is different" above.
• No local caching/dedup: every index_code call re-POSTs to the live Worker; re-indexing the same file just re-chunks/re-embeds/re-upserts it.

When to use the paid HTTP twin directly

Use POST /search on the live Worker instead of (in addition to) this MCP server when:

• You've indexed a repo with index_code and now want to actually search it semantically.
• Your agent already speaks x402 (e.g. via x402-fetch / x402-axios) and can pay $0.01 USDC on Base per query.
• You need production/high-volume search — this MCP server's index_code tool shares the same free /index endpoint as every other caller, but /search is metered per call regardless of caller.

License

MIT