x402-codesearch-mcp

x402-codesearch-mcp

一个免费的 MCP（Model Context Protocol）服务，可通过一个 MCP 工具 index_code，将仓库文件分块并生成嵌入，然后免费索引到实时语义代码搜索 Worker 中。

这是付费、由 x402 门控的 HTTP API 的开放入口孪生版本：

x402-codesearch-poc.theliminalguy.workers.dev — 对 /search 发送 POST 请求，每次查询通过 x402 支付协议在 Base 上支付 0.01 USDC，以执行已索引仓库的实际语义搜索步骤。

它与其他免费孪生版本有何不同（请先阅读）

像 x402-repohealth-mcp 这样的同系列软件包，会在本地完整重写付费 Worker 的逻辑（纯函数，不依赖绑定外部账户的服务），并通过 MCP 免费提供全部功能。

此软件包无法做到这一点。付费 Worker 的语义搜索依赖两个绑定到 Cloudflare 账户的绑定，且没有免费的本地或可移植替代方案：

• 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：

• 输入：{ 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 请求会返回 402 Payment Required，并附带真实的 x402 支付说明。

安装与运行

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 双生服务

在以下情况下，请直接对在线 Worker 使用 POST /search，而不是（或除了）使用此 MCP 服务：

• 你已使用 index_code 为仓库建立索引，现在想对其进行语义搜索。
• 你的 Agent 已支持 x402（例如通过 x402-fetch / x402-axios），并且可以为每次查询支付 $0.01 USDC（Base）。
• 你需要生产级／高容量搜索——此 MCP 服务的 index_code 工具与所有其他调用方共用同一个免费 /index 端点，但 /search 无论调用方是谁，都会按调用次数计费。

许可证

MIT