arcagents-mcp

Arc Agents MCP

什麼是 Arc Agents MCP？

Arc Agents MCP 是一個標準的模型上下文協定（MCP）伺服器，讓 AI 助手能夠存取 Arc 主網上的 ERC-8004 代理資料。ERC-8004 是一個用於代理身份、聲譽和驗證的鏈上註冊標準。

該伺服器從 Arc ERC-8004 瀏覽器（即 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 瀏覽器中該代理的連結，以及 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 瀏覽器介面中使用，但無法透過付費 API 或此 MCP 伺服器存取。
• 驗證資料取決於註冊合約的可用性，可能不存在。
• 代理活動目前無法透過此 API 取得。
• 該工具每次呼叫僅回傳一個代理 ID 的資料；沒有搜尋、列表或批次端點。
• 回應反映的是 fetchedAt 當時的狀態，並非即時更新。

資源

• Arc ERC-8004 瀏覽器：https://www.arcagents.app
• API OpenAPI 規格：https://www.arcagents.app/api/openapi.json
• MCP 儲存庫（各用戶端設定、組態、故障排除）：https://github.com/Nomad07/arcagents-mcp