mcp-server

# @gatefare/mcp [](https://www.npmjs.com/package/@gatefare/mcp) [](https://www.npmjs.com/package/@gatefare/mcp) [](https://bundlephobia.com/package/@gatefare/mcp) [](LICENSE) [](https://github.com/gatefareio/mcp-server/actions/workflows/ci.yml) [](https://registry.modelcontextprotocol.io/v0.1/servers?search=gatefareio) [](https://mcp.so/server/gatefare) [](https://glama.ai/mcp/servers/gatefareio/mcp-server) [](https://base.org) > 给你的 AI 代理一个钱包和一个市场。 > > `@gatefare/mcp` 是一个 Model Context Protocol 服务器，它连接 Claude > 桌面版、Cursor 或任何 MCP 兼容的代理到 [Gatefare](https://gatefare.io) 的付费 HTTP API 目录。付款 > 在 Base 上通过开放的 [x402](https://x402.org) 标准结算为 USDC —— 没有 SaaS 密钥，没有订阅，没有托管。非托管：签名 > 在本地进行；私钥永远不会离开你的机器。  ``` ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │ Claude / │ MCP stdio │ @gatefare/mcp│ HTTP + x402 │ gatefare.io │ │ Cursor / │ ─────────────► │ （此仓库）│ ─────────────► │ 代理 + │ │ 你的代理 │ │ │ │ 目录 │ └─────────────┘ └──────┬───────┘ └─────────────────┘ │ │ EIP-3009 签名 ▼ ┌─────────────┐ │ Base USDC │ └─────────────┘ ``` ## 快速开始 ### 1. 集成到你的客户端 **Claude 桌面版** — `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）： ```json { "mcpServers": { "gatefare": { "command": "npx", "args": ["-y", "@gatefare/mcp"] } } } ``` **Cursor** — `~/.cursor/mcp.json` 或项目级 `.cursor/mcp.json`： ```json { "mcpServers": { "gatefare": { "command": "npx", "args": ["-y", "@gatefare/mcp"] } } } ``` 重启客户端。现在代理拥有 5 个只读工具 — 发现 + 安全。尝试： > *"在 Gatefare 上搜索天气 API。"* ### 2. 添加钱包以进行付费调用 在同一配置中添加 `env`： ```json { "mcpServers": { "gatefare": { "command": "npx", "args": ["-y", "@gatefare/mcp"], "env": { "WALLET_PRIVATE_KEY": "0xYOUR_KEY", "WALLET_BUDGET_USD": "5.00" } } } } ``` 买家工具（`call_api`, `get_wallet_balance`, `estimate_cost`）变得可用。`WALLET_BUDGET_USD` 限制是一个运行时安全网 — 为了硬上限，资助钱包时 仅使用您愿意花费的金额。 > *"现在伦敦的天气怎么样？最多花费 $0.001。"* ### 3. （可选）发布您自己的 API 在 [gatefare.io/dashboard/tokens](https://gatefare.io/dashboard/tokens) 获取 PAT 并添加： ```json "env": { "GATEFARE_PAT": "gfpat_..." } ``` 发布者工具（`register_api`, `list_my_apis`, `update_api`, `get_revenue`, `distribute`）出现。 > *"在 https://api.example.com/sentiment 上发布我的 API，费用为每调用 $0.001。"* ## 工具 13 个工具，涵盖 4 个领域。工具根据设置的 env 变量自动注册 — 代理永远不会看到它无法使用的工具。 ### 发现 — 始终可用 | 工具 | 描述 | |------|-------------| | `gatefare.search_apis` | 使用筛选器（价格、类别、排序）对目录进行全文搜索 | | `gatefare.get_api` | 获取一个 API 的完整详细信息， slug 或 `handle/urlName` | | `gatefare.list_categories` | 所有类别及其 API 数量 | | `gatefare.suggest` | 查询字符串的自动完成建议 | ### 买家 — 需要 `WALLET_PRIVATE_KEY` | 工具 | 描述 | |------|-------------| | `gatefare.call_api` | 进行付费调用。自动处理 402 → 签名 → 重试 | | `gatefare.get_wallet_balance` | Base 上的 USDC + ETH，以及剩余的运行时预算 | | `gatefare.estimate_cost` | 计划调用的预计总成本 | ### 发布者 — 需要 `GATEFARE_PAT` | 工具 | 描述 | |------|-------------| | `gatefare.register_api` | 发布新的付费 API | | `gatefare.list_my_apis` | 您的已发布 API 及统计信息 | | `gatefare.update_api` | 编辑元数据、价格、目标 URL | | `gatefare.get_revenue` | 收入时间序列 + 总计 | | `gatefare.distribute` | 触发链上 `distribute()` 支付（破坏性） | ### 安全 — 始终可用 | 工具 | 描述 | |------|-------------| | `gatefare.report_abuse` | 举报恶意 / 盗窃 API（DMCA，欺诈，恶意软件……） | ## 配置 | 变量 | 默认值 | 所需工具 | |-----|---------|--------------| | `GATEFARE_BASE_URL` | `https://gatefare.io` | — （自托管的重写） | | `WALLET_PRIVATE_KEY` | — | 任何买家工具 | | `WALLET_BUDGET_USD` | 无限制 | 可选的支出上限 | | `WALLET_NETWORK` | `eip155:8453` | `eip155:84532` 用于 Sepolia 测试网 | | `GATEFARE_PAT` | — | 任何发布者工具 | | `LOG_LEVEL` | `info` | `debug` 用于详细的标准错误 | ## 示例 ### 在 Claude Desktop 上发现并购买（一步到位） > **你：** *为我找一个低于 $0.001 的天气 API 并为“Tokyo”调用它。* > > **Claude：** *使用 `max_price: 0.001` 调用 `gatefare.search_apis`…* > *找到 @alice 的 `demo-weather`，价格为 $0.001/调用。* > *使用 `slug: "demo-weather"` 调用 `gatefare.call_api`，`query: {city: "Tokyo"}`…* > *东京气温 22°C，部分多云。支付 0.001 USDC。结算凭证：`settled-tx-0x9a…`* ### 编程 — Python 代理 ```python from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client server = StdioServerParameters( command="npx", args=["-y", "@gatefare/mcp"], env={"WALLET_PRIVATE_KEY": "0x...", "WALLET_BUDGET_USD": "1.00"}, ) async with stdio_client(server) as (r, w): async with ClientSession(r, w) as s: await s.initialize() result = await s.call_tool( "gatefare.call_api", arguments={"slug": "demo-weather", "query": {"city": "Tokyo"}}, ) print(result.content[0].text) ``` 查看 [`examples/`](examples/) 以获取可运行的变体：Claude Desktop、Cursor、Python、 TypeScript 和纯发现演练。 ### 不是构建 AI 代理？选择合适的工具 如果您想 **从后端支付 x402 API（无代理）**，请使用 Coinbase 的 官方 x402 SDK — `x402-python`（PyPI）、`coinbase/x402/go`、`…/java` 或 [`@x402/fetch`](https://www.npmjs.com/package/x402-fetch）。它们处理 付款流程；您不需要此 MCP 服务器。 如果您想 **浏览 Gatefare 目录** 来自任何语言，请直接访问 REST API：[`gatefare.io/api/catalog`](https://gatefare.io/api/catalog) （[OpenAPI 3.1 规范](https://gatefare.io/openapi.json)）。 [`docs/integrations.md`](docs/integrations.md) 中有关于哪种工具适合哪种用例的完整分类。 ### 直接 CLI（用于调试） ```bash # 在前台运行服务器；通过 stdio 进行 JSON-RPC 通信。 npx -y @gatefare/mcp # 在另一个终端，发送一个帧： echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \ npx -y @gatefare/mcp ``` ## 错误 工具结果包括 `isError: true` 和结构化正文 `{ error: <code>, message: <human>, details?: <any> }`。代码是稳定的 — 代理可以根据它们进行重试/显示逻辑。 | 代码 | 含义 | |------|---------| | `INVALID_INPUT` | 输入失败 zod 验证 | | `WALLET_NOT_CONFIGURED` | 为买家工具设置 `WALLET_PRIVATE_KEY` | | `PAT_NOT_CONFIGURED` | 为发布者工具设置 `GATEFARE_PAT` | | `BUDGET_EXHAUSTED` | 运行时预算上限达到 | | `INSUFFICIENT_BALANCE` | 钱包中没有足够的 USDC | | `PRICE_TOO_HIGH` | 服务器的价格超过您的 `max_price` | | `API_NOT_FOUND` | 找不到或暂停 slug | | `UPSTREAM_ERROR` | 付费 API 返回非 2xx，或其 402 格式错误 | | `RATE_LIMITED` | Gatefare 对请求进行速率限制 | | `NETWORK_ERROR` | 无法访问 Gatefare | | `GATEFARE_API_ERROR` | Gatefare 返回 4xx / 5xx | ## 它是如何工作的（30 秒版本） 1. 代理调用 `gatefare.call_api { slug: "demo-weather", … }`。 2. 我们 `GET https://gatefare.io/p/demo-weather` （暂无付款）。 3. Gatefare 代理返回 **402 Payment Required**，包含 `accepts: [{network, payTo, maxAmountRequired, …}]`。 4. 我们为确切的金额和收款人在配置的网络上签署 [EIP-3009 `transferWithAuthorization`](https://eips.ethereum.org/EIPS/eip-3009)。 5. 我们使用签名的 `X-Payment` 头（base64 编码的 JSON，x402 v2）重试请求。 6. Gatefare 验证签名，结算 USDC，并将调用代理到上游 API。 7. 我们将上游响应（和付款凭证）返回给代理。 签名是一次性的、时间有限的，并且永远不会因任何 目的而离开您的机器以进行此确切的转账到确切的 `payTo`。私钥 永远不会被记录。 ## 安全 - **非托管。** 私钥存储在您的环境变量中，本地签名发生， 任何 Gatefare 服务都不会看到它们。 - **网络防混淆。** 恶意网关返回 Sepolia 仅限要求的 到主网用户被拒绝 — 我们永远不会为用户未配置的链签名。 - **加密随机数。** 没有基于 `Date.now()` 的冲突。 - **有效期限制在 1 小时内**，即使服务器请求更多。 - **严格的输入验证。** 斜杠是 `^[a-z0-9_-]+$` 并且 URL 编码； 没有路径遍历。`targetUrl` 阻止 `file://`、`localhost`、云 metadata IPs、`.local` 和 `.internal` 主机在注册时。 - **秘密卫生。** 测试断言私钥和 PAT 永远不会 出现在 stderr / stdout 中。 ## 开发 ```bash git clone https://github.com/gatefareio/mcp-server.git cd mcp-server npm install npm run typecheck npm test # 138 个单元测试 npm run test:e2e # 10 个 e2e 测试对抗 live gatefare.io（设置 GATEFARE_E2E=1） npm run build ``` 要在客户端配置中使用本地复位： ```bash npm link # 在 claude_desktop_config.json 中： # "command": "gatefare-mcp" ``` ### 架构 ``` src/ ├── index.ts # 入口 — 连接_stdio 传输 ├── server.ts # McpServer 实例 + 工具注册 ├── config.ts # 环境变量解析，功能检测 ├── client.ts # REST 客户端（包装 fetch） ├── x402.ts # 402 解析 + EIP-3009 签名 ├── types.ts # 共享类型 + GatefareError └── tools/ ├── discovery.ts # search_apis, get_api, list_categories, suggest ├── buyer.ts # call_api, get_wallet_balance, estimate_cost ├── publisher.ts # register_api, list_my_apis, update_api, get_revenue, distribute └── safety.ts # report_abuse ``` ### 测试布局 ``` tests/ ├── config.test.ts # 环境变量解析边缘 ├── client.test.ts # HTTP 客户端错误映射 ├── x402.test.ts # 签名 + 解析原语 ├── x402-flow.test.ts # 完整的 402 → 签名 → 重试握手（模拟 fetch） ├── server.test.ts # 功能驱动的工具注册 ├── init.test.ts # 子进程：引导，环境变量崩溃，秘密泄露 ├── stdio-protocol.test.ts # stdout 污染 + 从工具错误中恢复 ├── stability.test.ts # 100 个并发调用，内存基线，ReDoS ├── tools/ │ ├── discovery.test.ts │ ├── buyer.test.ts │ ├── buyer-flow.test.ts │ ├── publisher.test.ts │ └── safety.test.ts └── integration/ └── e2e.test.ts # 真实的 gatefare.io，由 GATEFARE_E2E=1 控制 ``` ## 贡献 问题和 PR 欢迎。查看 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取工作流程、 样式指南以及如何添加新工具。 ## 相关软件包 Gatefare 提供了三个第一方软件包。它们共享相同的 x402 协议和相同的后端，因此项目可以根据需要混合使用： | 软件包 | 哪里 | 何时使用 | |---|---|---| | [`@gatefare/mcp`](https://www.npmjs.com/package/@gatefare/mcp)（此软件包） | npm | 集成到 Claude Desktop / Cursor / 任何 MCP 主机以给代理提供目录发现 + 付费调用工具 | | [`@gatefare/client`](https://www.npmjs.com/package/@gatefare/client) | npm | TypeScript / JavaScript 代理在代码中支付 API，无需 MCP | | [`gatefare`](https://pypi.org/project/gatefare/) | PyPI | Python 代理（LangChain，LlamaIndex 等） | ## 许可证 [MIT](LICENSE) © Gatefare ## 链接 - 🌐 市场：[gatefare.io](https://gatefare.io) - 📚 API 文档：[gatefare.io/docs](https://gatefare.io/docs) - 🤖 LLM 上下文（单个文件）：[gatefare.io/llms-full.txt](https://gatefare.io/llms-full.txt) - 📐 OpenAPI 规范：[gatefare.io/openapi.json](https://gatefare.io/openapi.json) - 🐦 Twitter：[@Gatefareio](https://twitter.com/Gatefareio) - 🔌 Model Context Protocol：[modelcontextprotocol.io](https://modelcontextprotocol.io) - 💸 x402 标准：[x402.org](https://x402.org)