AntFeed

@antfeed/mcp

通过任意兼容 MCP 的 AI Agent，在 AntSeed P2P AI 网络中发现并进行交易。

一个 Model Context Protocol 服务，可将 AntFeed Explorer 转变为 Claude Code、Cursor、Claude Desktop 及任何其他 MCP 主机的一站式发现入口。列出卖家、查询提供方地址、检查链上支付通道，并且（在本地 AntSeed 买家正在运行时）开启新会话——所有操作都可在 Agent 内完成。

---

安装

将以下代码块添加到 ~/.claude.json（Claude Code）、claude_desktop_config.json（Claude Desktop）或 IDE 的 MCP 配置中：

{
  "mcpServers": {
    "antfeed": {
      "command": "npx",
      "args": ["-y", "@antfeed/mcp"],
      "env": {
        "ANTFEED_EXPLORER_URL": "https://www.antfeed.org",
        "ANTSEED_BUYER_URL": "http://localhost:8377"
      }
    }
  }
}

重启 MCP 主机。服务将通过 stdio 启动，并提供以下工具。

---

工具

每个工具都会返回 structuredContent（与其声明的 outputSchema 匹配的类型化对象）和 content[0].text（序列化为 JSON 的相同载荷，供旧版 MCP 客户端使用）。主机可通过注释（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），在执行破坏性调用前显示确认对话框，例如 Claude Desktop / Cursor。

工具	输入	输出	注释	需要本地买家？
lookup	query、limit?（1–200，默认值 50）、cursor?	{ query, matches[], matched, totalMatched, searchedOver, explorerTotal, truncated, nextCursor? } — 匹配 地址、显示名称和服务名称	只读、幂等	否
list_providers	limit?（1–200，默认值 50）、cursor?、sort?（score|recent）	{ providers[], total, sort, nextCursor? } — 每个服务提供方包含 displayName、region、services、pricingSummary、sessionCount、赚取的 USDC、ghost rate	只读、幂等	否
get_pricing	peerId、service	{ peerId, service, status, currency, inputUsdPerMillion, outputUsdPerMillion, displayName, region, lastUpdated } — 来自 AntFeed 目录的实时定价	只读、幂等	否
get_session_status	sessionId（channel_id，bytes32 十六进制）	{ sessionId, buyer, seller, status, channelBalance, settledAmountUsdc, totalDeltaUsdc, eventCount, settled, openedAt, closedAt }	只读	否
network_stats	（无）	{ revenueUsdc, dau, drift, gasGwei, asOf, partialFailures[] } — 某一时刻的快照（并行获取今天的 /api/stats + /api/gas + /api/metrics/dau；各端点的故障会使相应字段降级为 null，并列在 partialFailures 中）	只读	否
get_buyer	address	{ address, qualified, trustScore{…}, sessions{total, settledUsdc, monthlyVolume[]}, recentSessions[≤20], topSellers[] }	只读、幂等	否
dau_trend	from?（ISO 日期）、to?（ISO 日期）、granularity?（day）	{ from, to, granularity, series[{date, dau, dauBuyers, dauSellers, newUsers}] } — 默认时间范围：最近 30 天	只读	否
create_session	providerPeerId、service、initialDepositUsdc、initialMessage?	本地买家返回的 { sessionId, status, channelAddress?, txHash? }	破坏性	是
buyer_setup	（无）	安装本地 AntSeed 买家的诊断说明	只读	启动时未检测到买家时，会替代 create_session 暴露

示例：列出顶级服务提供方

// tool call
{ "name": "list_providers", "arguments": { "limit": 3, "sort": "score" } }

返回按赚取的 USDC 总额排名的前三位卖家。要翻页，请在下一次调用时将返回的 nextCursor 作为 cursor 传入。

数据源

该 MCP 封装了以下 AntFeed Explorer 端点：

• GET /api/providers — 服务提供方目录（displayName、服务、各服务定价、区域、链上汇总数据）。每小时从 network.antseed.com 刷新。为 list_providers 和 lookup 提供数据。
• GET /api/sellers/{address}/services — 单个卖家的服务目录和实时定价。为 get_pricing 提供数据。
• GET /api/channels — 链上支付通道记录。为 get_session_status 提供数据。
• GET /api/stats — 全网汇总数据（收入、会话数、漂移）。为 network_stats 提供数据。
• GET /api/gas — 当前 Base Gas 价格。为 network_stats 提供数据。
• GET /api/buyers/{address} + GET /api/score/{address} — 买家详情、会话历史、热门卖家和信任评分细分。为 get_buyer 提供数据。
• GET /api/metrics/dau — 按 UTC 日期统计的每日活跃用户数。为 dau_trend 和 network_stats 中的 DAU 字段提供数据。

目前还保留少量客户端适配：

• 尚无服务端 /api/search → lookup 会对 /api/providers 的第一页数据（最多 1000 个服务提供方）执行客户端子字符串匹配，匹配地址、displayName 和服务名称。未来添加服务端端点后，lookup 即可扩展到 1000 个以上的服务提供方，MCP 会自动切换，无需更改任何客户端。
• 尚无按通道查询的 /api/channels/{id} → get_session_status 会对 /api/channels 分页（按 last_activity desc 排序），并在客户端筛选。超过 5000 条记录的通道可能会返回 SESSION_OUT_OF_RANGE。

---

配置

所有值均为可选。解析顺序：--config file.json → 环境变量 → 内置默认值。

变量	默认值	用途
ANTFEED_EXPLORER_URL	https://www.antfeed.org	AntFeed Explorer REST API 的基址。
ANTSEED_BUYER_URL	http://localhost:8377	本地 AntSeed CLI 买家 RPC。AntStation Desktop 请使用 http://localhost:8378。
ANTFEED_MCP_TIMEOUT_MS	8000	Explorer 和买家调用的单次请求超时时间。
ANTFEED_MCP_LOG_LEVEL	info	可选值：debug、info、warn、error。日志写入 stderr（stdout 保留给 MCP stdio）。
ANTSEED_BUYER_STRICT	0	设为 1 时，要求本地买家的 /health 响应通过 {"service":"antseed-buyer"} 或 {"service":"antstation"} 表明自身身份。未设置时，MCP 会接受任何 200 响应，并在 stderr 上警告一次。建议在共享开发环境中启用。
ANTSEED_MAX_DEPOSIT_USDC	10	create_session 中 initialDepositUsdc 的硬性上限。用于纵深防御，防止受到提示词注入的 Agent 转移大额资金。买家本身也会执行身份验证；这是 MCP 侧的额外限额。

你也可以传入 --config path/to/config.json，并使用相同的键（camelCase：explorerUrl、buyerUrl、timeoutMs、logLevel、buyerStrict、maxDepositUsdc）。

---

买家自动检测

启动时，服务端会以 500 ms 超时探测 GET <ANTSEED_BUYER_URL>/health：

• 可访问 → 注册 create_session。
• 不可访问 → 改为注册 buyer_setup（提供安装说明的诊断工具），并从工具列表中省略 create_session。

检测仅在启动时执行一次。安装或启动买家后，请重启 MCP 宿主程序。

---

错误模型

每个工具都会返回成功的结构化负载，或带有 isError: true 且结构化正文符合以下形状的 MCP 错误结果：

{ "error": { "code": "EXPLORER_DOWN", "message": "..." } }

代码	含义
INVALID_INPUT	工具参数未通过 Zod 验证。
EXPLORER_DOWN	调用 explorer 时发生网络错误或超时。
EXPLORER_HTTP_<n>	Explorer 返回了非 2xx 状态（例如 EXPLORER_HTTP_404）。
RATE_LIMITED	Explorer 返回了 429。
EXPLORER_INVALID_JSON	响应正文不是 JSON。
BUYER_DOWN	无法访问本地 buyer。
BUYER_HTTP_<n>	本地 buyer 返回了非 2xx 状态。
BUYER_INVALID_JSON	Buyer 响应正文不是 JSON。
SESSION_NOT_FOUND	get_session_status 无法找到该频道。
BUYER_NOT_FOUND	get_buyer 无法在 explorer 的索引中找到该地址。
INVALID_CURSOR	cursor 参数不是之前调用返回的有效分页令牌。会显示为 INVALID_INPUT。
INTERNAL	其他所有情况（已清理；不含堆栈跟踪或环境变量值）。

---

安全模型

安装 @antfeed/mcp 是一项明确的信任决定。允许自主 Agent 调用其工具前，请阅读本节。

• 将 Agent 调用方视为不可信。 每个工具参数都会在任何网络调用前通过严格的 zod 模式验证。peerId/providerPeerId 必须为 0x + 40 个十六进制字符；sessionId 必须为 0x + 1–128 个十六进制字符；service 限定为较短的标识符；initialDepositUsdc 受 ANTSEED_MAX_DEPOSIT_USDC 严格限制（默认 10 USDC）。遭到提示词注入的 Agent 无法通过此 MCP 转移任意金额，也无法构造 URL/路径遍历负载。
• 将 explorer 视为半可信。 每个来自 ANTFEED_EXPLORER_URL 的响应都会根据严格的 zod 结构重新验证——地址必须为 40 位十六进制字符，频道 ID 必须为十六进制，数值字段必须为有限值。响应以流式方式传输，字节数上限为 2 MB，因此遭到入侵或劫持的端点无法耗尽内存。仅允许对环回主机使用纯 http://；非环回 URL 必须使用 https://。
• 本地 buyer 持有你的签名密钥；此 MCP 永远不会看到它。 MCP 只会向 buyer URL 发送 create_session POST 请求（使用受限的存款金额和经过验证的输入），不会读取或存储任何密钥材料。为防止其他本地进程冒充 buyer（例如在共享／多租户开发设备上），请设置 ANTSEED_BUYER_STRICT=1，并让你的 buyer 在 /health 响应 {"service":"antseed-buyer"}。
• 该软件包本身仅包含最少内容。 dist/、README、LICENSE——没有 postinstall 脚本、测试文件或会泄露本地路径的 source map。npm audit --omit=dev 报告生产依赖树中不存在漏洞。依赖项固定在 ~ 范围；发布时，软件包会使用 npm provenance 签名，以便使用者验证 tarball 来自此仓库（npm audit signatures）。
• 错误消息经过清理。 文件路径、IP 地址和 UPPER_CASE_VAR=… 模式会在任何错误传达给 Agent 或 MCP 主机日志前被清除。

如果你发现安全问题，请私下提交 GitHub 安全公告——我们会在 72 小时内进行分类处理。请勿针对影响安全的漏洞提交公开 issue。

面向卖家

如果你已经运营 AntSeed 卖家业务，并且出现在 AntFeed Explorer 目录中，就可以自动通过此 MCP 被发现，无需额外注册。新卖家只需在链上进行交易即可加入目录（Explorer 会为 Base 主网的 AntSeed Channels 事件建立索引）。/api/services 和 /api/sellers/{address}/services 上线后，get_pricing 和 list_providers#servicesOffered 将自动填充，无需更改客户端。

---

开发

npm install
npm run build         # tsc → dist/
npm test              # vitest, fully mocked, zero network
node dist/index.js    # stdio server (MCP host wires this up; not interactive)

使用官方检查器对 MCP 握手进行冒烟测试：

npx @modelcontextprotocol/inspector dist/index.js

---

注册表提交

此软件包已提交至公开的 MCP 服务注册表（registry.modelcontextprotocol.io、Smithery、PulseMCP、Glama、mcp.so），以便任何支持 MCP 的客户端都能发现并安装它，而无需复制粘贴上面的代码片段。官方注册表提交的权威来源是 server.json；Smithery 描述文件是 smithery.yaml。包含当前 URL 的完整提交检查清单位于 REGISTRIES.md。注册表仓库：https://github.com/modelcontextprotocol/registry。

如需查看 Vercel 仪表板上的逐工具使用情况监控，请参阅 USAGE.md。

链接

• AntFeed Explorer：https://antfeed.org
• AntFeed Explorer API 文档（OpenAPI 3.0）：https://antfeed.org/api/openapi.json
• AntSeed 协议合约（Base 主网）：请参阅 Explorer 的 About 页面

许可证

MIT