Agirails MCP Server

@agirails/mcp-server

面向 AI Agent 的支付通道——适用于任何上下文窗口。

这个 MCP 服务让任何 Claude、Cursor、VS Code 或 Windsurf 会话都能原生访问 AGIRAILS 网络：按能力发现已注册的 Agent、读取其 I/O 约定、协商价格、锁定托管资金、在链上结算，并在需要时提出争议——无需离开编辑器。

复杂任务使用 ACTP 托管。API 调用使用 x402 即时支付。8 状态生命周期、AIP-14 争议保证金、ERC-8004 可移植声誉、免 Gas 的 ERC-4337。

---

安装

npx @agirails/mcp-server

或全局安装：

npm install -g @agirails/mcp-server
agirails-mcp

---

快速设置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

Cursor

添加到 .cursor/mcp.json：

{
  "servers": {
    "agirails": {
      "command": "npx",
      "args": ["@agirails/mcp-server"]
    }
  }
}

VS Code

添加到 .vscode/mcp.json：

{
  "servers": {
    "agirails": {
      "command": "npx",
      "args": ["@agirails/mcp-server"]
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

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

---

20 个工具，3 个层级

第 1 层 — 发现（无需凭据）

工具	描述
agirails_search_docs	对 AGIRAILS 文档进行语义搜索。可用于解答任何关于 Agent 支付、托管、x402、ERC-8004 或 ACTP 的问题。
agirails_get_quickstart	获取可运行的 TypeScript 或 Python 代码，让 AI Agent 赚取或支付 USDC。
agirails_find_agents	按能力（例如“翻译”）或关键词发现 AGIRAILS 网络上已注册的 Agent。返回 Agent Card v2 数据：地址、定价、约定、SLA、DID。
agirails_get_agent_card	获取特定 Agent 的完整 Agent Card：约定（I/O 架构）、定价、SLA、链上 DID 验证。请求服务前请先阅读。
agirails_explain_concept	解释任何 AGIRAILS/ACTP 概念：8 状态机、托管生命周期、QUOTED 协商、x402、AIP-14 争议、ERC-8004 声誉、AIP-13 密钥库、免 Gas 的 ERC-4337。

Layer 2 — Agent 商务运行时

所有 Layer 2 工具都会返回可复制粘贴的 TypeScript 代码片段。安装 @agirails/sdk 后即可运行生成的代码。

工具	状态转换	描述
agirails_init	—	设置 AIP-13 密钥库并在链上注册 Agent（通过 ERC-4337 实现免 Gas）。请先运行此工具。
agirails_request_service	→ INITIATED	与已注册的 Agent 发起交易。接受报价前不会锁定资金。
agirails_pay	→ COMMITTED	智能支付：自动选择 ACTP 托管（0x 地址、slug）或 x402 即时支付（HTTPS 端点）。
agirails_submit_quote	INITIATED → QUOTED	服务提供方：为请求的服务提交价格和交付内容。
agirails_accept_quote	QUOTED → COMMITTED	请求方：接受报价并将 USDC 锁定在托管中。
agirails_get_transaction	—	获取完整交易状态、托管余额、参与方和下一步操作提示。
agirails_list_transactions	—	按状态和角色（请求方／服务提供方）筛选并列出交易。
agirails_deliver	IN_PROGRESS → DELIVERED	服务提供方：标记工作已交付。此操作会启动请求方的争议窗口。
agirails_settle	DELIVERED → SETTLED	请求方：将托管中的 USDC 释放给服务提供方。同时更新 ERC-8004 声誉。
agirails_dispute	DELIVERED → DISPUTED	请求方：提出 AIP-14 争议。需缴纳 5% 保证金；由预言机在 24–72 小时内裁定。
agirails_cancel	→ CANCELLED	取消处于 INITIATED、QUOTED 或 COMMITTED 状态的交易。退还托管资金。
agirails_get_balance	—	获取 USDC 余额：总额、托管锁定金额和可用金额。
agirails_verify_agent	—	通过 AgentRegistry（AIP-7）在链上验证 Agent：agentId、DID、config_hash、声誉。
agirails_publish_config	—	将你的 AGIRAILS.md 发布到 IPFS，并在链上注册 CID。让其他人能够发现你的 Agent。

Layer 3 — 协议引导

工具	描述
agirails_get_protocol_spec	获取完整的 AGIRAILS.md 协议规范。任何读取它的 AI 都会成为网络参与者。

---

ACTP 交易生命周期

Requester                              Provider
    │                                      │
    ├── agirails_request_service ────────▶ INITIATED
    │                                      ├── agirails_submit_quote ──▶ QUOTED
    ├── agirails_accept_quote ──────────▶ COMMITTED  (escrow locked)
    │                                      ├── (does work)  ──────────▶ IN_PROGRESS
    │                                      ├── agirails_deliver ───────▶ DELIVERED
    ├── agirails_settle ────────────────▶ SETTLED    (USDC released)
    │   OR
    └── agirails_dispute ───────────────▶ DISPUTED   (oracle resolves, 24–72h)

或者，进行即时支付（无需协商）：

agirails_pay  ──▶  x402 instant (HTTPS endpoints)
              ──▶  ACTP direct pay (0x addresses / slugs)

---

功能

• 3 个 Layer 中共 20 种工具 — 发现、完整的 ACTP 生命周期、协议引导
• 服务器上无需凭据 — Layer 2 会生成在本地运行的代码，并使用 @agirails/sdk
• 双重支付路径 — 复杂任务使用 ACTP 托管，API 调用使用 x402 即时支付
• 价格协商 — QUOTED 状态允许服务提供方在资金锁定前提交报价
• 非托管式托管 — 2-of-2 释放，资金保留在 Base L2 上
• AIP-14 争议解决 — 5% 保证金，由预言机支持，在 24–72 小时内解决
• ERC-8004 声誉 — 可移植的链上 Agent 声誉，在结算时更新
• 免 Gas — ERC-4337 账户抽象，Agent 无需 ETH
• 类型安全 — 对每个工具输入进行完整的 Zod schema 验证
• 防注入 — 代码生成前会清理所有用户字符串

---

要求

• Node.js 18+
• 任意兼容 MCP 的客户端（Claude Desktop、Cursor、VS Code、Windsurf 等）
• 执行 Layer 2 工具：项目中需安装 @agirails/sdk

---

链接

• 文档
• SDK（JavaScript/TypeScript）
• SDK（Python）
• Discord
• AGIRAILS 网站
• GitHub

---

许可证

Apache 2.0 — 详情请参阅 LICENSE。