@gatefare/mcp

npm version npm downloads bundle size License: MIT MCP Registry Base

为你的 AI 智能体配备钱包和市场。
@gatefare/mcp 是一个模型上下文协议 (MCP) 服务器，它将 Claude Desktop、Cursor 或任何兼容 MCP 的智能体连接到 Gatefare 付费 HTTP API 目录。支付通过开放的 x402 标准在 Base 上以 USDC 进行结算 — 无需 SaaS 密钥、无需订阅、无需托管。非托管：签名在本地完成；私钥永远不会离开你的机器。

Demo: install, list tools, real call against gatefare.io

┌─────────────┐                ┌──────────────┐                ┌─────────────────┐
│ Claude /    │   MCP stdio    │ @gatefare/mcp│  HTTP + x402   │ gatefare.io     │
│ Cursor /    │ ─────────────► │   (this repo)│ ─────────────► │ proxy +         │
│ your agent  │                │              │                │ catalog         │
└─────────────┘                └──────┬───────┘                └─────────────────┘
                                      │
                                      │ EIP-3009 sign
                                      ▼
                                ┌─────────────┐
                                │  Base USDC  │
                                └─────────────┘

快速开始

1. 放入你的客户端

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "mcpServers": {
    "gatefare": {
      "command": "npx",
      "args": ["-y", "@gatefare/mcp"]
    }
  }
}

Cursor — ~/.cursor/mcp.json 或项目级别的 .cursor/mcp.json：

{
  "mcpServers": {
    "gatefare": {
      "command": "npx",
      "args": ["-y", "@gatefare/mcp"]
    }
  }
}

重启客户端。智能体现在拥有 5 个只读工具 — 用于发现和安全。尝试：

“在 Gatefare 中搜索天气 API。”

2. 添加钱包以进行付费调用

在相同的配置中添加 env：

{
  "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 获取 PAT 并添加：

"env": {
  "GATEFARE_PAT": "gfpat_..."
}

发布者工具（register_api、list_my_apis、update_api、get_revenue、distribute）将会出现。

“发布我的 API 到 https://api.example.com/sentiment，价格为每次调用 $0.001。”

工具

涵盖 4 个领域的 13 个工具。工具会根据设置的环境变量自动注册 — 智能体永远不会看到它无法使用的工具。

发现 — 始终可用

工具	描述
`gatefare.search_apis`	使用过滤器（价格、类别、排序）对目录进行全文搜索
`gatefare.get_api`	通过 slug 或 `handle/urlName` 获取单个 API 的详细信息
`gatefare.list_categories`	包含 API 数量的所有类别
`gatefare.suggest`	查询字符串的自动补全建议

买家 — 需要 `WALLET_PRIVATE_KEY`

工具	描述
`gatefare.call_api`	进行付费调用。自动处理 402 → 签名 → 重试流程
`gatefare.get_wallet_balance`	Base 上的 USDC + ETH，以及剩余的运行时预算
`gatefare.estimate_cost`	预估 N 次计划调用的总成本

发布者 — 需要 `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`	Sepolia 测试网使用 `eip155:84532`
`GATEFARE_PAT`	—	任何发布者工具
`LOG_LEVEL`	`info`	详细 stderr 使用 `debug`

示例

一次性完成发现与购买 (Claude Desktop)

你： 帮我找一个低于 $0.001 的天气 API 并调用它查询“东京”。
Claude： 正在调用 gatefare.search_apis，参数 max_price: 0.001… 找到 @alice 提供的 demo-weather，价格为 $0.001/次调用。 正在调用 gatefare.call_api，参数 slug: "demo-weather", query: {city: "Tokyo"}… 东京目前 22°C，多云。已支付 0.001 USDC。收据：settled-tx-0x9a…

编程方式 — 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/ 获取可运行的变体：Claude Desktop、Cursor、Python、TypeScript 以及纯发现演练。

不构建 AI 智能体？选择正确的工具

如果你想从后端为 x402 API 付费（无智能体），请使用 Coinbase 官方的 x402 SDK — x402-python (PyPI)、coinbase/x402/go、…/java 或 @x402/fetch。它们处理支付流程；你不需要这个 MCP 服务器。

如果你想从任何语言浏览 Gatefare 目录，请直接访问 REST API：gatefare.io/api/catalog (OpenAPI 3.1 规范)。

关于哪个工具适合哪种用例的完整细分，请参阅 docs/integrations.md。

直接 CLI (用于调试)

# Run the server in foreground; talks JSON-RPC over stdio.
npx -y @gatefare/mcp

# In another terminal, send a frame:
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 秒版本)

智能体调用 gatefare.call_api { slug: "demo-weather", … }。
我们执行 GET https://gatefare.io/p/demo-weather（此时尚未支付）。
Gatefare 代理返回 402 Payment Required，包含 accepts: [{network, payTo, maxAmountRequired, …}]。
我们针对配置网络上的该金额和接收方签署 EIP-3009 transferWithAuthorization。
我们使用签名的 X-Payment 标头（base64 编码的 JSON，x402 v2）重试请求。
Gatefare 验证签名，结算 USDC 转账，并将调用代理到上游 API。
我们将上游响应（以及支付收据）交还给智能体。

签名是一次性的、有时限的，且除了针对此特定 payTo 的此特定转账外，绝不会出于任何目的离开你的机器。私钥永远不会被记录。

安全性

非托管。 私钥存在于你的环境变量中，签名在本地完成，Gatefare 服务永远无法看到它们。
抗网络混淆。 拒绝恶意网关向主网用户返回仅限 Sepolia 的要求 — 我们绝不会为用户未配置的链进行签名。
加密随机 Nonce。 没有基于 Date.now() 的冲突。
有效期限制为 1 小时，即使服务器请求更长时间。
严格的输入验证。 Slugs 为 ^[a-z0-9_-]+$ 且经过 URL 编码；无路径遍历。targetUrl 在注册时会阻止 file://、localhost、云元数据 IP、.local 和 .internal 主机。
密钥卫生。 测试断言私钥和 PAT 永远不会出现在 stderr / stdout 中。

开发

git clone https://github.com/gatefareio/mcp-server.git
cd mcp-server
npm install
npm run typecheck
npm test                  # 138 unit tests
npm run test:e2e          # 10 e2e tests against live gatefare.io (set GATEFARE_E2E=1)
npm run build

要在客户端配置中使用本地检出：

npm link
# in claude_desktop_config.json:
#   "command": "gatefare-mcp"

架构

src/
├── index.ts        # entry — wires stdio transport
├── server.ts       # McpServer instance + tool registration
├── config.ts       # env parsing, capability detection
├── client.ts       # REST client (wraps fetch)
├── x402.ts         # 402 parsing + EIP-3009 signing
├── types.ts        # shared types + 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         # env parsing edges
├── client.test.ts         # HTTP client error mapping
├── x402.test.ts           # signing + parsing primitives
├── x402-flow.test.ts      # full 402 → sign → retry handshake (mocked fetch)
├── server.test.ts         # capability-driven tool registration
├── init.test.ts           # subprocess: bootstrap, env crashes, secret leakage
├── stdio-protocol.test.ts # stdout pollution + recovery from tool errors
├── stability.test.ts      # 100 concurrent calls, memory baseline, ReDoS
├── tools/
│   ├── discovery.test.ts
│   ├── buyer.test.ts
│   ├── buyer-flow.test.ts
│   ├── publisher.test.ts
│   └── safety.test.ts
└── integration/
    └── e2e.test.ts        # real gatefare.io, gated by GATEFARE_E2E=1

贡献

欢迎提交 Issue 和 PR。请参阅 CONTRIBUTING.md 了解工作流程、风格指南以及如何添加新工具。

许可证

MIT © Gatefare

链接

🌐 市场：gatefare.io
📚 API 文档：gatefare.io/docs
🤖 LLM 上下文（单文件）：gatefare.io/llms-full.txt
📐 OpenAPI 规范：gatefare.io/openapi.json
🐦 Twitter：@Gatefareio
🔌 模型上下文协议：modelcontextprotocol.io
💸 x402 标准：x402.org

gatefareio/mcp-server

@gatefare/mcp

快速开始

1. 放入你的客户端

2. 添加钱包以进行付费调用

3. (可选) 发布你自己的 API

工具

发现 — 始终可用

买家 — 需要 `WALLET_PRIVATE_KEY`

发布者 — 需要 `GATEFARE_PAT`

安全 — 始终可用

配置

示例

一次性完成发现与购买 (Claude Desktop)

编程方式 — Python 智能体

不构建 AI 智能体？选择正确的工具

直接 CLI (用于调试)

错误

工作原理 (30 秒版本)

安全性

开发

架构

测试布局

贡献

许可证

链接

Maintenance

Resources

Latest Blog Posts

MCP directory API

@gatefare/mcp

快速开始

1. 放入你的客户端

2. 添加钱包以进行付费调用

3. (可选) 发布你自己的 API

工具

发现 — 始终可用

买家 — 需要 WALLET_PRIVATE_KEY

发布者 — 需要 GATEFARE_PAT

安全 — 始终可用

配置

示例

一次性完成发现与购买 (Claude Desktop)

编程方式 — Python 智能体

不构建 AI 智能体？选择正确的工具

直接 CLI (用于调试)

错误

工作原理 (30 秒版本)

安全性

开发

架构

测试布局

贡献

许可证

链接

Maintenance

Resources

Latest Blog Posts

MCP directory API

买家 — 需要 `WALLET_PRIVATE_KEY`

发布者 — 需要 `GATEFARE_PAT`