quai-mcp-server

Ein MCP-Server (Model Context Protocol), der Quai-Network-Kettendaten und schreibgeschützte Interaktionswerkzeuge für KI-Clients wie Claude Desktop und Claude Code bereitstellt. Gebaut mit dem offiziellen @modelcontextprotocol/sdk und quais, Quais ethers-ähnlichem SDK.

Was ist Quai Network, einfach erklärt

Quai ist eine Proof-of-Work-, EVM-kompatible Layer-1-Blockchain, die durch Sharding skaliert: Statt dass eine einzige Kette die ganze Arbeit erledigt, teilt sie sich in viele Ketten auf, die in einer Hierarchie angeordnet sind.

                Prime chain (1)
               /      |       \
        Region      Region      Region      <- "Cyprus", "Paxos", "Hydra"
       /  |  \      /  |  \     /  |  \
     Zone Zone Zone  ...              9 Zone chains total

• Prime ist die einzige oberste Kette. Jeder Miner schürft Prime; sie begleicht den Zustand über das gesamte Netzwerk, verarbeitet aber keine Benutzertransaktionen direkt.

• Region-Ketten (derzeit Cyprus, Paxos, Hydra) sitzen unter Prime und aggregieren ihre Zonen.

• Zone-Ketten (Cyprus1/2/3, Paxos1/2/3, Hydra1/2/3 – heute 9, weitere können hinzugefügt werden, wenn das Netzwerk wächst) sind dort, wo die eigentliche EVM lebt: Benutzertransaktionen, Verträge, Guthaben, alles.

Im Gegensatz zu Sharding-Designs, die Sicherheit zusammen mit Daten aufteilen, hält Quai die Sicherheit über die gesamte Hierarchie vereinheitlicht, während nur die Daten/der Durchsatz aufgeteilt werden – Prime- und Region-Ketten schürfen gemeinsam mit den darunterliegenden Zonen (Merge-Mining).

Der Teil, der für Werkzeuge am wichtigsten ist: Jede Quai-Adresse ist ortsbewusst. Die Bytes der Adresse selbst kodieren, in welcher einzelnen Zone sie lebt (und ob sie im QUAI-Ledger liegt, kontobasiert wie Ethereum, oder im Qi-Ledger, UTXO-basiert wie Bitcoin). Eine Adresse auf Cyprus1 existiert nur auf Cyprus1 – du kannst Paxos2 nicht danach fragen. Deshalb lösen mehrere der untenstehenden Werkzeuge die Zone entweder automatisch für dich auf oder bitten dich, eine explizit anzugeben.

Related MCP server: Kirha MCP Gateway

Werkzeuge

Schreibgeschützt

Keines dieser Werkzeuge kann Gelder bewegen, etwas signieren oder den On-Chain-Zustand ändern.

Wallets (verwahrend: verschlüsselt, benannt, passwortgeschützt)

Dieser Server verwahrt Schlüssel in deinem Namen, sobald du ein Wallet erstellst oder importierst – es ist in diesem engen, lokalen Sinne verwahrend, genauso wie ein geth-Keystore oder MetaMasks lokaler Tresor. Er arbeitet nicht als gehosteter Dienst für die Gelder anderer; alles befindet sich in einem Verzeichnis auf dem Rechner, der den Server ausführt, verschlüsselt mit einem Passwort, das nur du kennst.

So funktioniert die Verschlüsselung: Jedes Wallet ist ein privater Schlüssel im Standardformat Web3 Secret Storage (V3-Keystore) – dasselbe Format, das geth und MetaMask verwenden – über quais' encryptKeystoreJson. Konkret: Das Passwort wird mit scrypt gestreckt (N=2^17, r=8, p=1, die Standard-„teuren“ Kostenparameter – dies macht jeden Passwortversuch absichtlich langsam), der private Schlüssel wird mit AES-128-CTR verschlüsselt, und ein MAC über den Chiffretext erkennt ein falsches Passwort (oder eine manipulierte Datei), bevor Schlüsselmaterial daraus abgeleitet wird. Dies ist ein gut geprüftes, weit verbreitetes Schema; hier ist keine eigene Kryptografie im Spiel.

Wo Wallets leben: Standardmäßig unter ~/.quai-mcp-server/wallets/ (überschreibbar mit QUAI_WALLET_DIR) – QUAI-Wallets als <name>.json, Qi-Wallets als <name>.qi.json. Das Verzeichnis wird mit 0700 erstellt und jede Keystore-Datei mit 0600 (nur Eigentümer-Lesen/Schreiben, bestmöglich auf Nicht-POSIX-Plattformen) – explizit nach der Erstellung durchgesetzt, nicht nur der Prozess-Umask überlassen. Die Adresse wird in beiden Fällen im Klartext gespeichert (sie ist öffentliche Information; so funktionieren list_wallets und QUAI-seitige Vorschauen ohne Passwort), aber der private Schlüssel (oder die Mnemonik, bei Qi) wird von keinem Werkzeug jemals im Klartext geschrieben, protokolliert oder zurückgegeben.

Benennung: Ein Name identifiziert höchstens ein QUAI-Wallet und höchstens ein Qi-Wallet – sie sind unabhängige Keystores (verschiedene Dateien, verschiedene Geheimnisse, völlig unabhängiges Schlüsselmaterial), die zufällig ein Label teilen. Du kannst nicht zwei QUAI-Wallets (oder zwei Qi-Wallets) mit demselben Namen erstellen, aber die Wiederverwendung des Namens eines QUAI-Wallets für ein Qi-Wallet ist genau das, wie die Kopplung von create_wallet funktioniert, und create_qi_wallet/import_qi_wallet erlauben es aus demselben Grund bewusst.

Qi-Wallets sind unter der Haube HD-Wallets, aber dieser Server speichert nur die Mnemonik – niemals den abgeleiteten Adressbaum oder einen UTXO/Scan-Zustand. create_qi_wallet/import_qi_wallet verschlüsseln {address, privateKey, mnemonic} über denselben encryptKeystoreJson-Aufruf wie die QUAI-Seite (die Felder address/privateKey dort sind nur die erste abgeleitete Adresse des Wallets, vorhanden, damit die Datei ein normaler, gültiger V3-Keystore ist); das bedeutende Geheimnis ist die Mnemonik. Jede spätere Operation (get_qi_balance, convert_qi_to_quai) rekonstruiert ein frisches QiHDWallet aus dieser Mnemonik und leitet dieselbe Empfängeradresse bei Bedarf neu ab – deterministisch, da die HD-Ableitung für ein festes Konto/Zone immer dieselbe Adresse erzeugt. Dies wurde direkt verifiziert: Das Exportieren der Mnemonik eines Wallets und das erneute Importieren unter einem anderen Namen reproduzierte die identische Adresse. Der Kompromiss ist, dass jede Qi-Operation von Grund auf neu ableitet, anstatt einen Cache zu lesen, was einfacher zu durchdenken ist und nicht von dem abweichen kann, was die Mnemonik tatsächlich impliziert, auf Kosten dessen, dass das Passwort häufiger benötigt wird als auf der QUAI-Seite (siehe unten).

Warum Qi das Passwort häufiger benötigt: QUAIs get_balance liest einen öffentlichen Kontostand direkt von der Chain – kein Geheimnis nötig. Qi hat so etwas nicht: Ein „Kontostand“ ist die Summe nicht ausgegebener Transaktionsausgaben (UTXOs), die zu Adressen gehören, die nur der Mnemonic der Wallet ableiten kann. Daher erfordert die Berechnung überhaupt erst die Rekonstruktion der Wallet. Deshalb benötigt get_qi_balance ein Passwort (QUAIs get_balance nicht), und deshalb kann der Vorschau-Schritt von convert_qi_to_quai zwar einen Wechselkurs angeben, aber nicht bestätigen, dass du tatsächlich genug Qi zum Ausgeben hast – diese Prüfung erfolgt erst, wenn das Passwort im Bestätigungsschritt ankommt.

Passwortregeln: Mindestens 8 Zeichen, geprüft bevor irgendetwas verschlüsselt wird. Es gibt kein separates Rate-Limiting für falsche Passwortversuche – die Kostenparameter von scrypt machen jeden Versuch bereits rechenintensiv, was die Standardabwehr für diese Art von lokalem Keystore ist.

Bestätigungsablauf für send_transaction, convert_qi_to_quai und send_qi: Alle drei erfordern immer zwei Aufrufe, und nur der zweite benötigt das Passwort.

1. Aufruf mit Ziel und Betrag (walletName/to/amount für send_transaction; walletName/recipientPaymentCode/amount/destinationZone für send_qi; die to-förmige Variante für convert_qi_to_quai) – noch kein Passwort erforderlich. Es wird nichts gesendet. Du erhältst eine Vorschau – aufgelöste Zonen, eine Schätzung, wo eine existiert (Gas für einen Sendevorgang, umgerechneter Betrag für eine Konvertierung; send_qi hat keine, da es sich um eine 1:1-Übertragung handelt) – und ein confirmationToken, das 2 Minuten gültig ist.

2. Erneuter Aufruf mit denselben Parametern, plus confirm: true, diesem confirmationToken und dem password der Wallet. Erst dann wird der Schlüssel/Mnemonic entschlüsselt und die Transaktion tatsächlich signiert und gesendet.

Ein Token ist einmalig verwendbar und an die exakt in der Vorschau angezeigten Parameter gebunden – wenn sich etwas ändert, das Token abgelaufen ist oder bereits verwendet wurde, schlägt Schritt 2 mit einer klaren Fehlermeldung fehl und du erstellst erneut eine Vorschau. Dies funktioniert unabhängig davon, ob der MCP-Client selbst eine Tool-Genehmigungs-UI hat, sodass es eine echte Hürde darstellt und nicht darauf angewiesen ist, dass der Client eine bereitstellt. Ein falsches Passwort schlägt sauber fehl (Incorrect password for wallet "..."), ohne preiszugeben, ob Token/Parameter anderweitig gültig waren.

Es gibt bewusst kein export_wallet-/„Privaten Schlüssel oder Mnemonic anzeigen“-Tool – sobald ein Geheimnis im Speicher ist, ist der einzige Weg durch diesen Server, damit zu signieren.

QUAI ↔ Qi-Konvertierung („Swap“): Quai hat eine native, protokollebene Konvertierung zwischen seinen beiden Ledgern – QUAI (kontobasiert) und Qi (UTXO-basiert, wie Bitcoin) – mit einem On-Chain-Wechselkurs, nicht über einen Drittanbieter-DEX. get_conversion_rate gibt Kurse in beide Richtungen aus, ohne dass eine Wallet benötigt wird. Beide Ausführungsrichtungen sind jetzt implementiert:

• QUAI → Qi: einfach eine normale send_transaction an eine Qi-Ledger-Adresse (z. B. eine von create_qi_wallet). Das Tool erkennt dies automatisch (isConversion: true in der Vorschau) und zeigt die geschätzten erhaltenen Qi neben den üblichen Gas-/Kontostand-Informationen an.

• Qi → QUAI: convert_qi_to_quai, das intern quais' QiHDWallet.convertToQuai verwendet, nach demselben Vorschau-/Bestätigungs-/Passwort-Muster wie send_transaction.

Qi → Qi-Senden: Qi-Wallets senden nicht direkt an die Adressen anderer. Stattdessen hat jede Qi-Wallet einen wiederverwendbaren BIP-47-Zahlungscode (get_qi_payment_code) – teile ihn so, wie du eine Adresse teilen würdest, aber für jede Zahlung wird eine frische Einmaladresse daraus abgeleitet, aus Datenschutzgründen. Zum Senden „öffnet der Absender einen Kanal“ mit dem Zahlungscode des Empfängers (send_qi macht dies automatisch) – dies ist reines lokales ECDH zwischen den beiden Zahlungscodes, deterministisch und reproduzierbar, ohne On-Chain-Aktion oder gespeicherten Zustand. Der Haken liegt auf der Empfängerseite: Diese paarweise abgeleiteten Adressen sind nicht Teil der normalen deterministischen Adresssequenz der Wallet, sodass nichts Gelder findet, die auf diese Weise gesendet wurden, es sei denn, du weist es an. Konkret: Nachdem jemand deine Qi-Wallet per Zahlungscode bezahlt hat, übergib seinen Zahlungscode an get_qi_balance's counterpartyPaymentCodes – es öffnet denselben Kanal und nimmt ihn in den Kontostand auf. Es gibt keinen Benachrichtigungsmechanismus (on-chain oder anderweitig), der dem Empfänger mitteilt, dass eine Zahlung per Zahlungscode eingegangen ist; die beiden Seiten müssen sich bereits auf anderem Wege kennen, so wie du eine Adresse kennen müsstest, bevor du ihren Kontostand prüfst. send_qi unterstützt auch zonenübergreifende Sendungen (ein destinationZone getrennt von der eigenen Zone des Absenders), auf dieselbe Weise wie send_transaction's ETX und QiHDWallet's eigenes Zonenmodell.

Eine bekannte Unschönheit: Der Vorschau-Schritt von send_qi validiert das Format des Zahlungscodes nicht im Voraus (es gibt keinen exportierten Validator, um es dagegen zu prüfen), sodass ein fehlerhafter Code in der Vorschau gut aussieht und erst bei der Bestätigung fehlschlägt – sicher (es wird nichts gesendet, keine Gelder sind gefährdet), nur später als ideal.

Noch nicht implementiert: deploy_contract, request_faucet.

Ehrlichkeit darüber, was hier getestet wurde, aktualisiert: Die vollständige send_qi-/Zahlungscode-Schleife wurde live gegen das Mainnet mit zwei echten Wallets verifiziert – ein echter, korrekt formatierter BIP-47-Zahlungscode (PM8T...) wurde generiert und als deterministisch über Aufrufe hinweg bestätigt, eine Vorschau erkannte korrekt zonenübergreifend vs. gleiche Zone, eine Bestätigung gegen eine leere Wallet schlug mit einem echten SDK-Fehler fehl (No Qi available in zone) statt abzustürzen, und get_qi_balance isolierte korrekt einen ungültigen Gegenpartei-Zahlungscode in rejectedPaymentCodes, ohne den gesamten Aufruf fehlschlagen zu lassen. Was weiterhin unverifiziert ist, aus demselben Grund wie überall sonst in diesem Dokument: eine tatsächliche Zahlungscode-Sendung, die zwischen zwei finanzierten Wallets abgeschlossen wird, da dies echtes Qi erfordert und nicht ohne Aufforderung durchgeführt wurde.

Ehrlichkeit darüber, was hier getestet wurde: Alles oben Genannte wurde gegen das Live-Mainnet ausgeführt, einschließlich eines Deterministik-Checks (Exportieren des Mnemonics einer Qi-Wallet und erneutes Importieren unter einem anderen Namen reproduzierte die identische Adresse) und echter Fehlerpfade (falsches Passwort, unzureichendes QUAI-Gas und ein echter QiHDWallet-Fehler – No Qi available in zone – beim Versuch, aus einer leeren Qi-Wallet zu konvertieren). Was nicht ausgeführt wurde, ist eine convert_qi_to_quai- oder QUAI→Qi-Konvertierung, die tatsächlich gegen eine Wallet mit echten Geldern abgeschlossen wird, da dies echtes Geld erfordert und nicht ohne Aufforderung durchgeführt wurde.

Installation

npm install
npm run build

Oder direkt ohne Installation ausführen, sobald veröffentlicht:

npx quai-mcp-server

Anforderungen

• Node.js 18+

Konfiguration (Umgebungsvariablen)

Alle optional – sinnvolle Standardwerte zeigen auf das Quai-Mainnet.

Jedes Tool akzeptiert auch ein network-Argument ("mainnet" oder "testnet") pro Aufruf, sodass ein Client entweder Netzwerk abfragen kann, ohne den Server neu zu starten.

Zu Schlüsseln: Siehe „Wallets“ oben. Schlüssel existieren nur als Klartext im Speicher für die Dauer eines create_wallet/import_wallet/send_transaction-Aufrufs, der sie benötigt – niemals auf der Festplatte, niemals protokolliert. Behandle QUAI_WALLET_DIR (und die Maschine, auf der dieser Server läuft) wie jeden anderen lokalen Geheimnisspeicher: Jeder mit Dateisystemzugriff auf dieses Verzeichnis und genug Rechenleistung, um ein schwaches Passwort zu brute-forcen, kann letztendlich eine Wallet entschlüsseln, genauso wie bei einem lokalen geth-Keystore oder MetaMask-Vault.

Bei Claude Desktop registrieren

Füge dies zu deiner MCP-Konfiguration von Claude Desktop hinzu (claude_desktop_config.json – auf macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "quai": {
      "command": "npx",
      "args": ["quai-mcp-server"]
    }
  }
}

Oder, wenn du dieses Repo lokal geklont und gebaut hast, statt ein veröffentlichtes Paket zu verwenden:

{
  "mcpServers": {
    "quai": {
      "command": "node",
      "args": ["/absolute/path/to/quai-mcp-server/dist/index.js"]
    }
  }
}

Um es standardmäßig auf das Testnet auszurichten, füge einen env-Block hinzu:

{
  "mcpServers": {
    "quai": {
      "command": "npx",
      "args": ["quai-mcp-server"],
      "env": {
        "QUAI_TESTNET_RPC_URL": "https://orchard.rpc.quai.network"
      }
    }
  }
}

(dann übergib "network": "testnet" in einzelnen Tool-Aufrufen – die Umgebungsvariablen setzen den Endpunkt, nicht das Standard-Netzwerk pro Aufruf).

Bei Claude Code registrieren

claude mcp add quai -- npx quai-mcp-server

oder, für einen lokalen Build:

claude mcp add quai -- node /absolute/path/to/quai-mcp-server/dist/index.js

Entwicklung

npm run dev     # tsc --watch
npm run build   # one-shot build to dist/
npm start        # run the built server directly (stdio) -- mainly useful for manual smoke tests

Der Server spricht in v1 nur MCP über stdio; es gibt keinen HTTP-Transport.

Designhinweise

• quais über Raw-RPC: Jedes Tool läuft über JsonRpcProvider, Contract und die Adress-Utilities des quais-SDK statt über handgeschriebene eth_/quai_-JSON-RPC-Aufrufe, sodass Zonenauflösung, Antwortformatierung und Fehlerformen konsistent mit dem Rest des Quai-Ökosystems bleiben.

• Ein Provider, viele Zonen: Ein einzelner JsonRpcProvider, der auf eine Basis-Gateway-URL zeigt (z. B. https://rpc.quai.network), erkennt aktive Zonen automatisch von der Prime-Chain und leitet jeden Aufruf an die richtige weiter – die meisten Tools konstruieren nie eine pro-Zonen-URL.

• Verwahrung mit Standard-Tools, nicht mit benutzerdefinierter Krypto: Wallets werden mit quais' Implementierung des Ethereum-V3-Keystore-Formats gespeichert (scrypt + AES-128-CTR + MAC) – dasselbe gut geprüfte Schema, das geth und MetaMask verwenden – statt mit etwas Handgeschriebenem. Siehe „Wallets“ oben für das vollständige Modell.

• Fehler sind Text, keine Stacktraces: RPC-/Vertragsfehler werden abgefangen und in kurze, spezifische Meldungen umgeschrieben (z. B. „Contract call reverted: ...“, „Insufficient funds: ...“, „Incorrect password for wallet...“, „not a validly checksummed Quai address“), statt rohe Ausnahmeobjekte an das Modell durchzulassen.

• Bestätigung ist eine echte Hürde, nicht nur ein Client-Hinweis: Schreib-Tools sind mit readOnlyHint: false annotiert (und destructiveHint: true für das Senden), sodass MCP-Clients mit eigener Genehmigungs-UI eine anzeigen, aber send_transaction erzwingt zusätzlich seinen eigenen Vorschau-→-Token-→-Passwort-Handshake serverseitig (src/confirmations.ts für das Token, src/walletStore.ts + decryptKeystoreJson für das Passwort), sodass es auch von einem Client ohne Genehmigungs-UI sicher aufgerufen werden kann.

• Passwort nur einmal nötig, im letzten Moment: Das Vorschauen eines Sendevorgangs löst die Adresse der Wallet direkt aus dem unverschlüsselten Teil ihrer Keystore-Datei auf und verwendet einen VoidSigner (einen quais-Signer, der Gas schätzen, aber nicht signieren kann), um die Kosten zu schätzen – keine Entschlüsselung, kein Passwort. Nur der finale confirm: true-Aufruf entschlüsselt den Schlüssel, und nur für die Dauer dieses einen Aufrufs.

• ETX ist kein separater Codepfad: Das Senden an eine Adresse in einer anderen Zone verwendet exakt denselben send_transaction-Aufruf wie eine Sendung in derselben Zone – Quais Netzwerk übernimmt die zonenübergreifende Weiterleitung (als externe Transaktion) transparent, sobald die signierte Transaktion die Zone des Absenders erreicht. Das Tool erkennt und meldet nur die beteiligten Zonen, damit der Aufrufer weiß, was zu erwarten ist.

• Qi-Wallets sind bewusst zustandslos zwischen Aufrufen: create_qi_wallet/import_qi_wallet verschlüsseln nur einen Mnemonic. get_qi_balance und convert_qi_to_quai rekonstruieren die QiHDWallet bei jedem Aufruf von Grund auf und leiten ihre Adresse neu ab (src/qiWallet.ts), statt einen gecachten Adress-/UTXO-Zustand zu lesen – es gibt keinen zu lesen. Dies tauscht etwas Leistung (jede Qi-Operation leitet neu ab und fragt neu ab, statt einen Cache zu treffen) gegen eine einfachere, schwerer falsch zu machende Sicherheitsgeschichte: Das Einzige, was jemals im Ruhezustand ist, ist das eine Geheimnis, das zählt.