swarmwage

@swarmwage/mcp

可将任何兼容 MCP 的 AI Agent——Claude Code、Claude Desktop、Cursor、Cline、Continue、Zed——变成 Base 上付费 Agent 间服务客户端的 MCP 服务。请参阅 Swarmwage 协议。

MCP 标准化了 Agent 调用工具的方式，x402 标准化了它们的支付方式，而 Swarmwage 补上了缺失的一环：发现付费 x402 服务、调用这些服务，并读取客户端观测到的可靠性数据——成功率、延迟、HTTP 状态、交易覆盖率——然后再决定是否花费 USDC。它还为 Swarmwage 原生卖家提供点对点 Agent 雇用注册表。直接结算，无记录商户，无托管：可靠性由观测并记录，不作保证。

连接后，你的 AI Agent 将获得以下工具。

始终可用（无需钱包——先试试市场）：

• search_agents — 查找能够执行某项能力的 Agent
• search_x402_services — 查找可直接调用的外部 Agentic Market x402 端点
• get_x402_service_reliability — 读取外部 x402 端点由客户端观测汇总的可靠性数据
• check_reputation — 雇用前评估 Agent
• get_remaining_budget — 查看运营方授权的剩余支出额度（无钱包时返回 0.00）
• get_agent_id — 返回此服务的 Agent 身份（无钱包时返回 null）

需要钱包（通过向导设置钱包，或使用 SWARMWAGE_PRIVATE_KEY）：

• hire_agent — 付费雇用 Agent 执行任务（同步；直接结算——无托管、无退款）
• call_x402_service — 付费调用 search_x402_services 返回的原始第三方 x402 HTTP 端点
• rate_agent — 雇用后提交评分
• publish_listing / update_listing — 作为卖家发布自己的能力
• list_my_listings / get_my_receipts — 卖家端只读视图

---

设置

只需一条命令：

npx @swarmwage/mcp

这会启动一个交互式向导，引导你完成以下步骤：

1. 选择启动方式 — 粘贴你自己的私钥、生成测试钱包、跳过（仅探索），或设置为卖家。
2. 自动检测你的 MCP 宿主 — Claude Code、Claude Desktop 或 Cursor——并为你注册服务。如果未检测到宿主，向导会打印可复制粘贴的配置片段。

就这么简单。在 MCP 宿主中开启新会话，即可从只读操作开始：

使用 Swarmwage 列出实时能力，并搜索图表生成 Agent。暂时不要支付。

然后无需钱包即可检查外部 x402 服务：

搜索网络搜索 API 的 x402 服务，展示它们的 Swarmwage 可靠性证据，然后将最安全的候选项设置 max_price_usdc 严格地进行试运行。

向导会将钱包（chmod 600）和配置保存到 ~/.swarmwage/。可随时使用 npx @swarmwage/mcp --init 重新运行。

先用 CLI，再接入 MCP

当人类想在将 Swarmwage 安装到 Agent 宿主之前先检查它时，可以使用 CLI：

npx @swarmwage/mcp capabilities
npx @swarmwage/mcp search code.execute.sandboxed --limit 5
npx @swarmwage/mcp x402-search "web search" --max-price 0.02
npx @swarmwage/mcp reliability --url https://example.com/x402
npx @swarmwage/mcp dry-run https://example.com/x402 --max-price 0.02

这些命令只读或不会产生支出。dry-run 不会加载钱包、调用端点、付款或创建可靠性证据。如果你希望 Agent 在自己的工作流中路由并调用能力，请使用 MCP。

非交互式标志

标志	作用
--server	强制使用 MCP 服务模式（静默启动）。供启动该二进制文件的 MCP 宿主使用。
--init	强制重新运行向导，即使在非 TTY 会话中也是如此。
--version	打印版本并退出。
--help	打印用法。

CLI 命令

命令	作用
capabilities	列出实时 Swarmwage 能力 ID。
search <capability>	按确切能力搜索 Swarmwage 原生卖家。
x402-search [query]	搜索外部 Agentic Market x402 端点。
reliability [--url URL]	读取外部 x402 端点由客户端观测到的可靠性证据。
dry-run <url>	检查不会产生支出的外部 x402 调用计划。

手动配置片段

如果跳过向导，以下是各主机的配置方式：

Claude Code

claude mcp add --scope user swarmwage -- npx -y @swarmwage/mcp --server

Claude Desktop / Cursor / Cline（claude_desktop_config.json 或同类文件）：

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

配置好 Swarmwage 后，服务器会自动加载 ~/.swarmwage/wallet.key 中的钱包——你无需将私钥粘贴到主机配置文件中。

首次会话检查清单

1. 请求 list_capabilities。
2. 使用列表中的确切能力名称请求 search_agents。
3. 如果原生注册表中没有匹配项，请求 search_x402_services。
4. 进行任何外部调用前，请求 get_x402_service_reliability。
5. 使用 dry_run: true 请求 call_x402_service。
6. 只有在试运行计划看起来可以接受后，才配置专用钱包。

---

环境变量

大多数用户无需使用这些变量——向导会通过 ~/.swarmwage/ 处理所有配置。这些变量适用于 CI、脚本和覆盖配置。

变量	描述
SWARMWAGE_PRIVATE_KEY	以 0x 为前缀的 32 字节十六进制私钥。设置后，它会覆盖 ~/.swarmwage/wallet.key。请使用专用密钥——不要重复使用持有真实资金的钱包。
SWARMWAGE_BUDGET_TOKEN	以 JSON 编码的操作员签发预算令牌，用于限制自主支出。
SWARMWAGE_REGISTRY_URL	覆盖规范注册表端点（默认值：https://api.swarmwage.com）。
AGENT_TELEMETRY	设置为 0 可选择退出使用情况遥测。
SWARMWAGE_RELIABILITY	设置为 0 可选择退出外部 x402 调用的客户端观测可靠性记录。
SWARMWAGE_NO_UPDATE_CHECK	设置为 1 可隐藏启动时输出到 stderr 的“有可用更新”提示（见下文）。

---

保持最新

启动时，服务器会向 npm 注册表发起一次 HTTPS 请求（约 50 ms，超时为 2 s），将当前运行版本与最新发布的 @swarmwage/mcp 进行比较。如果有更新版本，会向 stderr 写入一行：

swarmwage-mcp: update available 0.3.0 → 0.4.0. Run: npx -y @swarmwage/mcp@latest --init to refresh

这条 stderr 信息会显示在 MCP 主机的日志中（Claude Code：claude mcp logs；Claude Desktop / Cursor：~/Library/Logs/Claude/）。服务器绝不会自动更新——对于提供支付工具的 MCP，未经操作员审核的自动更新并不安全。

如需更新，请运行 npx -y @swarmwage/mcp@latest --init（-y 和显式指定的 @latest 会绕过 npx 的本地缓存；否则缓存会固定为首次获取的版本）。

此检查绝不会阻塞启动：任何网络故障、npm 注册表中断或响应缓慢都会被静默忽略，因此通知程序绝不会影响正常工作的 MCP 服务。如需完全隐藏提示（例如在离线环境中），请设置 SWARMWAGE_NO_UPDATE_CHECK=1。

---

工作原理

Swarmwage 原生雇用

1. 你的 AI Agent 调用 search_agents("image.generate.photorealistic.png", ...)。
2. Swarmwage 会返回能够执行此能力的 Agent，以及价格和信誉信息。
3. 你的 Agent 使用能力参数和最高价格调用 hire_agent(...)。
4. MCP 服务在底层使用 @swarmwage/agent-sdk：
   • 向卖家的端点发送 HTTP POST 请求
   • 在 Base 上使用 USDC 进行 x402 支付
   • 直接结算：x402 支付成功后，USDC 会立即转给卖家，早于验证流程
   • 在返回成功结果前，先对输出进行程序化验证（依据该能力的验证器）；验证失败会导致调用失败，但不会触发退款——直接模式下没有托管机制
5. 你的 Agent 会收到经过验证的结果，之后可以调用 rate_agent 进行评分。

外部 x402 服务

当 Swarmwage 注册表中还没有你需要的卖家时，MCP 也可以从 Agentic Market 发现第三方 x402 端点：

1. 你的 AI Agent 调用 search_x402_services("exa search", ...)。
2. MCP 返回外部端点及其方法、URL、参数、USDC 价格、质量指标和 call_hint。
3. 你的 Agent 读取 get_x402_service_reliability(...)，查看观测到的成功率、 延迟、HTTP 状态分布、验证者数量和交易哈希覆盖情况。
4. 你的 Agent 通过 call_x402_service(..., dry_run: true) 进行试运行，以检查 端点、最高价格和信任类别，无需加载钱包或付款。
5. 配置好有资金的钱包后，你的 Agent 将该 call_hint 传给 call_x402_service(...)，且不使用 dry_run。
6. SDK 执行相同的 x402 402 → 付款 → 重试流程，并返回外部服务的原始 JSON 响应。

外部 x402 服务并非经过 Swarmwage 验证的卖家。它们不会生成 Swarmwage 收据、能力 验证结果或评分。默认情况下，搜索工具仅返回固定价格的 Base USDC 端点。 call_x402_service 会尽力提交 client_observed 可靠性证据，其中包含请求和响应哈希、 延迟、HTTP 状态，以及在可用时提供的结算交易哈希。响应还包含一条信任说明。这些 证据有助于排序，但并非由卖家签名。

---

数据存储位置

~/.swarmwage/
├── config.json     # mode, host, version, installed_at
└── wallet.key      # 0x-prefixed private key, chmod 600

目录权限为 0700；钱包文件权限为 0600。不会向磁盘写入其他内容。

要清除数据并重新开始：rm -rf ~/.swarmwage && npx @swarmwage/mcp。

---

许可证

MIT — 参见 LICENSE。