arcagents-mcp

Arc Agents MCP

Was ist Arc Agents MCP?

Arc Agents MCP ist ein standardkonformer Model Context Protocol (MCP) Server, der KI-Assistenten Zugriff auf ERC-8004-Agentendaten im Arc Mainnet gewährt. ERC-8004 ist ein On-Chain-Registrierungsstandard für Agentenidentität, Reputation und Validierung.

Der Server liest aus der kostenpflichtigen API des Arc ERC-8004 Explorers – der Arc Agents Plattform – unter https://www.arcagents.app. Er stellt ein Tool, get_agent_data, zur Verfügung und bezahlt jede Anfrage automatisch aus einer vom Benutzer kontrollierten Wallet.

Schnellstart

Der Benutzer (nicht Sie) verbindet den Server, indem er ihn in seine MCP-Client-Konfiguration einfügt. Der Startbefehl lautet:

npx -y [email protected]

Voraussetzungen:

• Node.js 20 oder neuer.
• Ein EVM-Wallet-Private-Key, bereitgestellt als Umgebungsvariable EVM_PRIVATE_KEY (0x gefolgt von 64 Hexadezimalzeichen). Er signiert die Zahlung für jede Anfrage. Empfohlen wird eine dedizierte Wallet mit nur einem kleinen USDC-Guthaben, niemals die Haupt-Wallet des Benutzers. -Optional: ARCAGENTS_PAYMENT_NETWORK=arc|base wählt aus, welches Netzwerk die Anfragen bezahlt. Standard ist arc.

Beispielkonfiguration (die meisten Clients verwenden diese mcpServers-Struktur; der Platzhalter muss vom Benutzer in seiner eigenen Konfigurationsdatei ersetzt werden):

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

Regeln für Sie:

• Bitten Sie den Benutzer niemals, einen Private Key im Chat einzugeben, einzufügen oder zu offenbaren. Wenn ein Schlüssel im Gespräch auftaucht, wiederholen Sie ihn nicht und teilen Sie dem Benutzer mit, ihn zu rotieren.
• Verweisen Sie den Benutzer auf die Projekt-README für die clientspezifische Einrichtung: https://github.com/Nomad07/arcagents-mcp
• Wenn das get_agent_data-Tool nicht verfügbar ist, teilen Sie dem Benutzer mit, dass der Server nicht verbunden ist, und zeigen Sie die obigen Einrichtungsschritte. Versuchen Sie nicht, die Daten auf andere Weise abzurufen und als von diesem Tool stammend auszugeben.

Verfügbares Tool

get_agent_data

• Eingabe: agentId, eine positive ganze Zahl: die ERC-8004-Agenten-ID (Token-ID), zum Beispiel 15.
• Verhalten: Ruft die ERC-8004-Informationen dieses Agenten aus Arc Mainnet ab und gibt die JSON-Antwort der API zurück.
• Kosten: 0,002 USDC pro erfolgreicher Anfrage.

Validieren Sie die Eingabe vor dem Aufruf: Die ID muss eine positive ganze Zahl sein. Raten Sie keine IDs. Fragen Sie den Benutzer, wenn keine ID angegeben wurde.

Jeder Aufruf kostet Geld. Rufen Sie das Tool nicht wiederholt „zum Überprüfen“ oder in Massenschleifen auf, es sei denn, der Benutzer hat danach gefragt. Verwenden Sie bereits in der Konversation zurückgegebene Daten erneut, anstatt sie erneut abzurufen.

Die kostenpflichtige API bedient nur Arc Mainnet. Behaupten oder implizieren Sie nicht, dass sie Arc Testnet, Base oder ein anderes Netzwerk liest. Base ist nur ein mögliches Zahlungsnetzwerk.

Verfügbare Daten

Die Antwort kann Folgendes enthalten. Geben Sie nur das tatsächlich in der Antwort Vorhandene an.

• Identität und Registrierung: agentId, network, chainId und die Adressen der Identitäts-, Reputations- und Validierungsregister.
• Besitzer und Agent-Wallet: die Besitzeradresse und die designierte Agent-Wallet.
• Metadaten: der Metadaten-URI (IPFS oder HTTPS) und die geparsten Metadaten, wenn sie abgerufen werden konnten: Name, Beschreibung, Dienste, active, x402Support. Wenn die Metadaten nicht abgerufen werden konnten, ist metadata null und metadataError erklärt den Grund.
• Reputation: Anzahl der Kunden, Anzahl der Feedback-Einträge, Gesamtbewertung, Kunden und einzelne Feedback-Datensätze (Client, Index, Wert, Tags, isRevoked).
• Validierung: ob Validierungsdaten verfügbar sind, ein Grund, wenn nicht, die Anzahl der Anfragen sowie Validierungsanfragen und -antworten, falls vorhanden.
• Links und Zeitstempel: Links zum Agenten im Arc ERC-8004 Explorer und die fetchedAt-Zeit.

Einige Felder können nicht verfügbar sein. Abhängig vom Agenten und den bereitgestellten Registry-Verträgen können Werte null, leer oder fehlend sein, und Validierungsdaten können vollständig fehlen. Das ist normal. Sagen Sie, dass ein Feld nicht verfügbar ist; füllen Sie es niemals aus.

Nach einem erfolgreichen bezahlten Aufruf kann der Server einen zweiten Textblock mit dem Zahlungstransaktions-Hash und einem Explorer-Link hinzufügen. Der erste Block ist immer das API-JSON.

Anwendungsbeispiele

Daten für einen Agenten abrufen

„Rufe die ERC-8004-Daten für Agent 15 ab.“ Rufen Sie get_agent_data mit agentId: 15 auf und präsentieren Sie dann die Hauptfelder.

Registrierung und Metadaten erklären

„Was ist Agent 8 und wie ist er registriert?“ Rufen Sie das Tool auf und erklären Sie dann Besitzer, Agent-Wallet, Metadaten-URI und Registrierungen. Beschreiben Sie Dienste nur, wenn sie in den Metadaten enthalten sind. Wenn metadataError gesetzt ist, berichten Sie dies, anstatt zu raten, was die Metadaten aussagen.

Reputations-Feedback zusammenfassen

„Wie wird Agent 14 bewertet?“ Berichten Sie clientCount, feedbackCount, aggregateScore und eine kurze Zusammenfassung der Feedback-Datensätze, wobei Sie widerrufene Einträge erwähnen. Wenn es kein Feedback gibt, sagen Sie dies.

Zwei Agenten vergleichen

„Vergleiche Agent 1 und Agent 8.“ Führen Sie einen Aufruf pro ID durch (zwei kostenpflichtige Anfragen; informieren Sie den Benutzer) und vergleichen Sie dann dieselben Felder nebeneinander. Wenn ein Feld für einen Agenten existiert, aber nicht für den anderen, sagen Sie dies, anstatt fehlende Daten als Null zu behandeln.

Fehlende Informationen identifizieren

„Was wissen wir nicht über Agent 22?“ Listen Sie nach dem Aufruf die Felder auf, die null, leer oder als nicht verfügbar markiert sind, wie z. B. metadata, validation.available und dessen reason. Machen Sie klar, dass diese nicht verfügbar sind, und leiten Sie keine Werte ab.

Unterscheiden Sie bei der Beantwortung, was die API zurückgegeben hat, von Ihrer eigenen Interpretation, und erwähnen Sie, dass die Daten von Arc Mainnet zum Zeitpunkt fetchedAt stammen.

Zahlungen

• Protokoll: x402 Version 2, Schema exact (eine EIP-3009-Übertragungsautorisierung), abgewickelt durch den Ultravioleta DAO Facilitator.
• Preis: 0,002 USDC (2000 atomare Einheiten, 6 Dezimalstellen) pro erfolgreicher Anfrage. Es gibt keine Abonnements oder monatlichen Gebühren.
• Unterstützte Zahlungsnetzwerke:
  • Arc Mainnet (eip155:5042), der Standard
  • Base Mainnet (eip155:8453)
• Funktionsweise: Die Zahlungsaufforderung der API listet die akzeptierten Optionen auf. Der Server wählt genau eine aus, passend zu ARCAGENTS_PAYMENT_NETWORK, und zahlt direkt an den von dieser Zahlungsanforderung angegebenen Empfänger. Er prüft Token, Betrag und Signaturdomäne vor dem Signieren. Er wechselt nach einem Fehler nie zum anderen Netzwerk.
• Unterstützung des Zahlungsprotokolls: nur x402. Beschreiben Sie kein anderes Zahlungsprotokoll, einschließlich MPP, als unterstützt.
• Die zahlende Wallet benötigt USDC im ausgewählten Netzwerk. Der Benutzer benötigt keine nativen Gas-Token für die Zahlung.

Zahlungssicherheit und Fehlerbehandlung

• Bitten Sie den Benutzer niemals, seinen Private Key preiszugeben, und fügen Sie niemals einen in Tool-Aufrufen, Dateien oder Nachrichten ein.
• Wiederholen Sie niemals eine kostenpflichtige Anfrage, indem Sie eine neue Zahlung erstellen, wenn das vorherige Ergebnis unsicher ist. Versuchen Sie nicht, Fehler zu umgehen, indem Sie mitten in einer Anfrage Netzwerke, Wallets oder Einstellungen ändern.
• Der Server speichert den ausstehenden Zahlungsstatus lokal (in ~/.arcagents-mcp oder ARCAGENTS_STATE_DIR), bevor er eine signierte Zahlung sendet. Wenn eine Anfrage unterbrochen wird, wird durch erneutes Fragen nach derselben Agenten-ID die abgebrochene Anfrage fortgesetzt: Der Server sendet die identische signierte Zahlung erneut und signiert keine neue. Dies funktioniert auch nach einem Neustart des MCP-Servers.
• 503, ein Timeout oder eine unvollständige Antwort bedeutet, dass möglicherweise noch kein endgültiges Ergebnis vorliegt. Melden Sie dies dem Benutzer, respektieren Sie einen eventuellen Retry-After-Wert und rufen Sie nach dieser Verzögerung get_agent_data erneut mit derselben agentId auf. Der Server setzt denselben Zahlungskontext fort, anstatt doppelt zu bezahlen. Wiederholen Sie nicht in einer engen Schleife.
• 409-Konflikt (die Autorisierung wurde bereits verwendet oder gehört zu einer anderen Anfrage) darf keine neue Autorisierung auslösen. Melden Sie den reason in der Antwort wie angegeben: authorization_already_settled bedeutet, dass der Facilitator meldet, dass diese Autorisierung bereits verwendet und ihre Zahlung bestätigt wurde; receipt_request_conflict bedeutet, dass sie zu einer anderen Anfrage gehört, und die API sagt nicht, ob diese Zahlung abgewickelt wurde. Raten Sie nicht, welche. Der Server behält die vorhandene signierte Zahlung und wird keine neue für diese Agenten-ID erstellen.
• 402 nach Zahlung bedeutet, dass die API die Zahlung nicht akzeptiert hat. Melden Sie den in der Antwort angegebenen Grund. Es ist eine endgültige Antwort; eine erneute Anfrage startet eine neue Anfrage.
• 500 bedeutet, dass die Abwicklung fehlgeschlagen ist oder nicht bestätigt werden konnte. Signieren oder fordern Sie keine neue Zahlung an; informieren Sie den Benutzer und geben Sie einen eventuellen Transaktions-Hash in der Antwort weiter. Eine erneute Anfrage für dieselbe Agenten-ID sendet nur dieselbe signierte Zahlung erneut.
• 404 bedeutet, dass die Agenten-ID nicht auf Arc Mainnet gemintet wurde; die Anfrage wird nicht berechnet.
• Eine Nachricht wie „ein anderer Prozess hält bereits eine signierte, ungelöste Zahlung“ ist ein temporärer Konflikt. Nur ein Prozess kann eine Zahlung für eine Anfrage beanspruchen und senden, und der konkurrierende Prozess sendet nichts. Fragen Sie später erneut; die vorhandene Zahlung wird wiederverwendet.
• Behaupten Sie nicht, dass eine Anfrage kostenlos, unbezahlt oder nicht berechnet wurde, wenn ihr Zahlungsergebnis ungewiss ist. Sagen Sie, dass das Ergebnis nicht bestimmt werden konnte und was die Antwort dazu angibt.
• Erfinden Sie keine Agentendaten, Transaktions-Hashes, Kontostände oder Zahlungsergebnisse. Wenn das Tool einen Fehler zurückgibt, zitieren Sie den Fehler und seine Anleitung, anstatt ihn in etwas Optimistischeres umzuformulieren.

Einschränkungen

• Die Daten der kostenpflichtigen API decken nur Arc Mainnet-Agenten ab.
• Testnet ist in der Oberfläche des Arc ERC-8004 Explorers verfügbar, jedoch nicht über die kostenpflichtige API oder diesen MCP-Server.
• Validierungsdaten hängen von der Verfügbarkeit des Registers ab und können fehlen.
• Agentenaktivität ist derzeit über diese API nicht verfügbar.
• Das Tool gibt Daten für eine Agenten-ID pro Aufruf zurück; es gibt keinen Such-, Listen- oder Bulk-Endpunkt.
• Antworten spiegeln den Zeitpunkt von fetchedAt wider und werden nicht live aktualisiert.

Ressourcen

• Arc ERC-8004 Explorer: https://www.arcagents.app
• API OpenAPI-Spezifikation: https://www.arcagents.app/api/openapi.json
• MCP-Repository (Einrichtung für jeden Client, Konfiguration, Fehlerbehebung): https://github.com/Nomad07/arcagents-mcp