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](https://x402-codesearch-poc.theliminalguy.workers.dev)**
— `POST /search`, $0.01 USDC on Base per query via the
[x402 payment protocol](https://x402.org), 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`](https://github.com/liminalpepe/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

```bash
npx x402-codesearch-mcp
```

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

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

## Tool: `index_code`

Input:

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

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

```jsonc
{
  "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

```bash
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