l402-search-mcp

l402-search-mcp

为 AI Agent 提供免 KYC 的网页搜索 — 通过 MCP 按查询次数使用 Lightning sats 付费。

这是一个面向 L402 付费墙搜索端点的 MCP 客户端侧服务。它为任何支持 MCP 的 Agent（Claude Desktop、Claude Code、Cursor、nostr-merchant 等）提供一个 search 工具，用 sats 而非 API 密钥付费：

1. search(query) → 返回一张 bolt11 Lightning 发票和 payment_hash
2. Agent 使用自己的钱包支付发票 — 例如调用 nwc-mcp 的 nwc_pay_invoice，并遵循 Agent 自身的预算上限
3. search(query, payment_preimage) → 返回 JSON 结果

无需账户。无需 API 密钥。无需 KYC。每次付款恰好购买一次搜索。

默认情况下，它连接到 **https://llmops-search.fly.dev**（每次搜索 50 sats，由我们运营），但 SEARCH_SERVICE_URL 也可用于任何使用相同 L402 方言的端点。

信任模型（请阅读）

此服务不持有任何密钥。 无钱包连接，也没有 nsec，什么都没有。付款通过 Agent 的钱包完成，并受 Agent 自身的预算上限、允许列表和审计日志约束。l402-search-mcp 只负责：

• 将 L402 挑战（发票）转发给 Agent，
• 记录哪个 macaroon 对应哪个 payment_hash（这样 Agent 只需处理其钱包已返回的 preimage），
• 发起授权后的重试。

最坏情况下，此进程遭到入侵只会泄露待处理的搜索查询 — 绝不会造成资金损失。

安装

npx -y l402-search-mcp

Claude Code（项目范围）：

claude mcp add l402-search -s project -- npx -y l402-search-mcp

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "l402-search": { "command": "npx", "args": ["-y", "l402-search-mcp"] }
  }
}

将它与钱包服务（例如 nwc-mcp）配对，这样 Agent 才能实际付款。

工具

工具	价格	功能
search	sats（由端点设定；默认值为 50）	首次调用返回发票；附带 payment_preimage 的调用返回结果。
search_service_info	免费	端点连通性、待处理挑战和流程说明。

配置

所有配置项均为可选 — 默认设置即可使用。在环境变量中设置，或在安装目录旁放置 .env 文件（绝不从 cwd 读取）：

SEARCH_SERVICE_URL=https://llmops-search.fly.dev  # any L402 search endpoint
CHALLENGE_TTL_SECONDS=900                          # match the endpoint's macaroon TTL
AUDIT_LOG_PATH=./l402-search-mcp-audit.log         # NDJSON, append-only
HTTP_TIMEOUT_MS=15000

完整流程

agent                    l402-search-mcp              endpoint              agent's wallet
  │  search("foo")            │                          │                       │
  │ ────────────────────────► │  GET /search?q=foo       │                       │
  │                           │ ───────────────────────► │                       │
  │                           │  402 {macaroon, invoice} │                       │
  │  {invoice, payment_hash}  │ ◄─────────────────────── │                       │
  │ ◄──────────────────────── │  (macaroon cached)       │                       │
  │  nwc_pay_invoice(invoice) │                          │                       │
  │ ──────────────────────────┼──────────────────────────┼─────────────────────► │
  │  {preimage}               │                          │                       │
  │ ◄─────────────────────────┼──────────────────────────┼────────────────────── │
  │  search("foo", preimage)  │                          │                       │
  │ ────────────────────────► │  GET + Authorization:    │                       │
  │                           │  L402 macaroon:preimage  │                       │
  │                           │ ───────────────────────► │                       │
  │  {results}                │  200 {results}           │                       │
  │ ◄──────────────────────── │ ◄─────────────────────── │                       │

macaroon 不会经由 LLM 往返传递 — Agent 只会看到发票，并传回钱包返回的 preimage。sha256(preimage) = payment_hash 可恢复其余信息。

审计日志

NDJSON，每个事件占一行：startup、challenge_received、results_received、unknown_preimage、endpoint_error。格式与工具包中的其他服务相同。

属于 LLMOps.Pro Agent 付款工具包

nwc-mcp（钱包） · nostr-ops-mcp（NOSTR 身份/发布） · marketplace-mcp（店面） · albyhub-admin-mcp（节点管理） · paywall-mcp（用 sats 出售你的工具） · l402-search-mcp（用 sats 购买搜索）

MIT。由 LLMOps.Pro 构建 · ⚡ [email protected]