arcagents-mcp

Arc Agents MCP

什么是 Arc Agents MCP？

Arc Agents MCP 是一个标准的模型上下文协议（MCP）服务器，它使 AI 助手能够访问 Arc 主网上的 ERC-8004 代理数据。ERC-8004 是一个用于代理身份、声誉和验证的链上注册标准。

该服务器从 Arc ERC-8004 Explorer（即 Arc Agents 平台）的付费 API 读取数据，平台地址为 https://www.arcagents.app。它暴露了一个工具 get_agent_data，每次请求的费用会自动从用户控制的钱包中支付。

快速开始

用户（而不是你）需要通过将服务器添加到他们的 MCP 客户端配置中来连接它。启动命令是：

npx -y [email protected]

要求：

• Node.js 20 或更高版本。
• 一个 EVM 钱包私钥，通过环境变量 EVM_PRIVATE_KEY 提供（0x 后跟 64 个十六进制字符）。它用于为每个请求签署支付。建议使用一个专用钱包，只持有少量 USDC 余额，切勿使用用户的主钱包。
• 可选：ARCAGENTS_PAYMENT_NETWORK=arc|base 选择哪个网络来支付请求。默认是 arc。

配置块示例（大多数客户端使用这种 mcpServers 结构；占位符必须由用户在自己的配置文件中替换）：

{
  "mcpServers": {
    "arcagents": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "EVM_PRIVATE_KEY": "YOUR_EVM_PRIVATE_KEY",
        "ARCAGENTS_PAYMENT_NETWORK": "arc"
      }
    }
  }
}

给你的规则：

• 切勿要求用户在聊天中粘贴、输入或透露私钥。如果对话中出现了密钥，不要重复它，并告知用户轮换该密钥。
• 引导用户查看项目 README 以了解针对各个客户端的设置方法：https://github.com/Nomad07/arcagents-mcp
• 如果 get_agent_data 工具不可用，请告知用户服务器未连接，并分享上述设置步骤。不要尝试以其他方式获取数据并将其作为来自此工具的数据呈现。

可用工具

get_agent_data

• 输入： agentId，一个正整数：ERC-8004 代理 ID（代币 ID），例如 15。
• 行为： 从 Arc 主网 检索该代理的 ERC-8004 信息，并返回 API 的 JSON 响应。
• 费用： 每次成功请求 0.002 USDC。

在调用之前验证输入：ID 必须是一个正整数。不要猜测 ID。如果未提供 ID，请询问用户。

每次调用都会产生费用。不要为了“检查”而重复调用工具，也不要在用户未要求时进行批量循环调用。请复用对话中已返回的数据，而不是重新获取。

付费 API 仅服务于 Arc 主网。不要声称或暗示它可以读取 Arc 测试网、Base 或任何其他网络。Base 仅作为可能的支付网络。

可用数据

响应可以包含以下内容。仅报告响应中实际存在的内容。

• 身份和注册： agentId、network、chainId，以及身份、声誉和验证注册表地址。
• 所有者和代理钱包： 所有者地址和指定的代理钱包。
• 元数据： 元数据 URI（IPFS 或 HTTPS）以及在可以获取时解析出的元数据：名称、描述、服务、active、x402Support。如果无法获取元数据，则 metadata 为 null，并且 metadataError 会解释原因。
• 声誉： 客户数量、反馈数量、聚合评分、客户列表以及单个反馈记录（客户、索引、值、标签、isRevoked）。
• 验证： 验证数据是否可用，不可用时的原因，请求数量，以及验证请求和响应（如果存在）。
• 链接和时间戳： 指向 Arc ERC-8004 Explorer 中该代理的链接以及 fetchedAt 时间。

某些字段可能不可用。 根据代理和已部署的注册表合约，值可能为 null、空或缺失，并且验证数据可能完全不存在。这是正常的。请说明某个字段不可用；切勿填充它。

在成功付费调用后，服务器可能会添加第二个文本块，其中包含支付交易哈希和浏览器链接。第一个块始终是 API JSON。

使用示例

检索代理数据

“获取代理 15 的 ERC-8004 数据。”调用 get_agent_data，参数 agentId: 15，然后呈现主要字段。

解释注册信息和元数据

“代理 8 是什么，它是如何注册的？”调用该工具，然后解释所有者、代理钱包、元数据 URI 和注册表。仅当元数据中存在时才描述服务。如果设置了 metadataError，请报告它，而不是猜测元数据内容。

总结声誉反馈

“代理 14 的评分如何？”报告 clientCount、feedbackCount、aggregateScore，并简要总结反馈记录，注意已撤销的条目。如果没有反馈，请说明。

比较两个代理

“比较代理 1 和代理 8。”为每个 ID 调用一次工具（两次付费请求；告知用户），然后并排比较相同字段。如果某个字段对于一个代理存在而对另一个不存在，请说明这一点，而不是将缺失数据视为零。

识别缺失信息

“我们对代理 22 不了解什么？”调用工具后，列出那些为 null、空或标记为不可用的字段，例如 metadata、validation.available 及其 reason。明确说明这些字段不可用，并且不要推断值。

回答时，请区分 API 返回的内容和你自己的解释，并提及数据来自 Arc 主网，截至 fetchedAt 时间。

支付

• 协议： x402 版本 2，方案 exact（EIP-3009 转账授权），通过 Ultravioleta DAO 促进器结算。
• 价格： 每次成功请求 0.002 USDC（2000 个原子单位，6 位小数）。没有订阅费或月费。
• 支持的支付网络：
  • Arc 主网（eip155:5042），默认
  • Base 主网（eip155:8453）
• 工作原理： API 的支付挑战列出了接受的选项。服务器选择恰好一个，与 ARCAGENTS_PAYMENT_NETWORK 匹配，并直接支付给该支付要求指定的接收者。它在签署前会检查代币、金额和签署域。在失败后，它永远不会切换到另一个网络。
• 支付协议支持： 仅支持 x402。不要描述任何其他支付协议（包括 MPP）为受支持。
• 付款人钱包需要在所选网络上有 USDC。用户无需支付原生 gas 代币。

支付安全与错误处理

• 切勿要求用户透露其私钥，也切勿在工具调用、文件或消息中包含私钥。
• 当先前结果不确定时，切勿通过创建新的支付来重试付费请求。 不要在请求中途尝试通过更改网络、钱包或设置来解决问题。
• 服务器在发送已签名的支付之前，会本地保存待处理支付状态（在 ~/.arcagents-mcp 或 ARCAGENTS_STATE_DIR 中）。如果请求被中断，再次请求 相同的代理 ID 会恢复该请求：服务器会重新发送相同的已签名支付，而不会签署一个新的。这在 MCP 服务器重启后也同样适用。
• 503 错误、超时或不完整响应 意味着可能还没有最终结果。将此情况报告给用户，尊重任何 Retry-After 值，并在该延迟之后，使用相同的 agentId 再次调用 get_agent_data。服务器会恢复相同的支付上下文，而不是重复支付。不要紧密循环重试。
• 409 冲突（授权已使用，或属于另一个请求）不得触发新的授权。按原样报告响应中的 reason：authorization_already_settled 意味着促进器报告该授权已被使用且其支付已确认；receipt_request_conflict 意味着它属于另一个请求，并且 API 未说明该支付是否已结算。不要猜测是哪种情况。服务器会保留现有的已签名支付，并且不会为该代理 ID 创建新的支付。
• 支付后的 402 错误 意味着 API 未接受该支付。报告响应中给出的原因。这是一个最终答案，因此再次询问会开始一个新的请求。
• 500 错误 意味着结算失败或无法确认。不要签署或请求新的支付；告知用户并传递响应中的任何交易哈希。为相同的代理 ID 再次询问只会重新发送相同的已签名支付。
• 404 错误 意味着该代理 ID 在 Arc 主网上尚未铸造；该请求不会收费。
• 诸如“另一个进程已持有一个已签名且未解决的支付”的消息是一个临时冲突。只有一个进程可以声明并发送一个支付的请求，竞争进程不会发送任何东西。稍后再试；现有的支付会被复用。
• 当支付结果不确定时，不要声称一个请求是免费的、未付费或未被收费。请说明无法确定结果以及响应的说明。
• 不要捏造代理数据、交易哈希、余额或支付结果。如果工具返回错误，请引用该错误及其指导，而不是将其转述为更乐观的内容。

限制

• 付费 API 数据仅覆盖 Arc 主网代理。
• 测试网在 Arc ERC-8004 Explorer 界面中可用，但无法通过付费 API 或此 MCP 服务器访问。
• 验证数据取决于注册表的可用性，并且可能不存在。
• 代理活动目前无法通过此 API 获取。
• 该工具每次调用只返回一个代理 ID 的数据；没有搜索、列表或批量端点。
• 响应反映 fetchedAt 时刻的数据，不会实时更新。

资源

• Arc ERC-8004 Explorer：https://www.arcagents.app
• API OpenAPI 规范：https://www.arcagents.app/api/openapi.json
• MCP 仓库（每个客户端的设置、配置、故障排除）：https://github.com/Nomad07/arcagents-mcp