quai-mcp-server

Un servidor MCP (Model Context Protocol) que expone datos de la cadena de Quai Network y herramientas de interacción de solo lectura a clientes de IA como Claude Desktop y Claude Code. Construido con el oficial @modelcontextprotocol/sdk y quais, el SDK similar a ethers de Quai.

Qué es Quai Network, en términos sencillos

Quai es una Capa 1 compatible con EVM y prueba de trabajo que escala mediante fragmentación (sharding): en lugar de que una sola cadena haga todo el trabajo, se divide en muchas cadenas organizadas en una jerarquía.

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

• Prime es la única cadena de nivel superior. Cada minero mina Prime; esta asienta el estado en toda la red pero no procesa transacciones de usuarios directamente.

• Las cadenas Region (actualmente Cyprus, Paxos, Hydra) se sitúan bajo Prime, agregando sus Zonas.

• Las cadenas Zone (Cyprus1/2/3, Paxos1/2/3, Hydra1/2/3 — 9 hoy, se pueden añadir más a medida que la red crezca) son donde vive la EVM real: transacciones de usuarios, contratos, saldos, todo.

A diferencia de los diseños de fragmentación que dividen la seguridad junto con los datos, Quai mantiene la seguridad unificada en toda la jerarquía mientras que solo se dividen los datos/rendimiento — Prime y las cadenas Region minan en conjunto con las Zonas que tienen debajo.

La parte que más importa para las herramientas: cada dirección de Quai es consciente de su ubicación. Los propios bytes de la dirección codifican en qué única Zona vive (y si está en el libro mayor QUAI, basado en cuentas como Ethereum, o en el libro mayor Qi, basado en UTXO como Bitcoin). Una dirección en Cyprus1 solo existe en Cyprus1 — no puedes preguntarle a Paxos2 sobre ella. Por eso varias herramientas de abajo o resuelven la zona automáticamente, o te piden que especifiques una explícitamente.

Related MCP server: Kirha MCP Gateway

Herramientas

Solo lectura

Ninguna de estas puede mover fondos, firmar nada o cambiar el estado en cadena.

Carteras (de custodia: cifradas, con nombre, protegidas por contraseña)

Este servidor guarda claves en tu nombre una vez que creas o importas una cartera — es de custodia en ese sentido estrecho y local, de la misma manera que un almacén de claves de geth o la bóveda local de MetaMask. No opera como un servicio alojado para fondos de otras personas; todo vive en un directorio en la máquina que ejecuta el servidor, cifrado con una contraseña que solo tú conoces.

Cómo funciona el cifrado: cada cartera es una clave privada en el formato estándar Web3 Secret Storage (V3 keystore) — el mismo formato que usan geth y MetaMask — a través de encryptKeystoreJson de quais. Concretamente: la contraseña se estira con scrypt (N=2^17, r=8, p=1, los parámetros de costo "caros" estándar — esto hace deliberadamente lento cada intento de adivinar la contraseña), la clave privada se cifra con AES-128-CTR, y un MAC sobre el texto cifrado detecta una contraseña incorrecta (o un archivo manipulado) antes de que se derive cualquier material de clave de él. Este es un esquema bien revisado y ampliamente desplegado; nada aquí es criptografía personalizada.

Dónde viven las carteras: ~/.quai-mcp-server/wallets/ por defecto (anulable con QUAI_WALLET_DIR) — carteras QUAI como <nombre>.json, carteras Qi como <nombre>.qi.json. El directorio se crea con 0700 y cada archivo de almacén de claves con 0600 (solo lectura/escritura del propietario, mejor esfuerzo en plataformas no POSIX) — aplicado explícitamente después de la creación, no solo dejado al umask del proceso. La dirección se almacena en claro en ambos casos (es información pública; así es como list_wallets y las vistas previas del lado QUAI funcionan sin contraseña), pero la clave privada (o mnemónico, para Qi) nunca se escribe, registra o devuelve en texto plano por ninguna herramienta.

Nombres: un nombre identifica como máximo una cartera QUAI y como máximo una cartera Qi — son almacenes de claves independientes (archivos diferentes, secretos diferentes, material de clave completamente no relacionado) que casualmente comparten una etiqueta. No puedes crear dos carteras QUAI (o dos carteras Qi) con el mismo nombre, pero reutilizar el nombre de una cartera QUAI para una cartera Qi es exactamente cómo funciona el emparejamiento de create_wallet, y create_qi_wallet/import_qi_wallet lo permiten deliberadamente por la misma razón.

Las carteras Qi son carteras HD bajo el capó, pero este servidor solo almacena el mnemónico — nunca el árbol de direcciones derivado ni ningún estado de UTXO/escaneo. create_qi_wallet/import_qi_wallet cifran {address, privateKey, mnemonic} mediante la misma llamada encryptKeystoreJson que el lado QUAI (los campos address/privateKey allí son solo la primera dirección derivada de la cartera, presentes para que el archivo sea un almacén V3 normal y válido); el secreto significativo es el mnemónico. Cada operación posterior (get_qi_balance, convert_qi_to_quai) reconstruye un QiHDWallet fresco desde ese mnemónico y re-deriva la misma dirección receptora bajo demanda — de forma determinista, ya que la derivación HD para una cuenta/zona fija siempre produce la misma dirección. Esto se verificó directamente: exportar el mnemónico de una cartera y re-importarlo bajo un nombre diferente reprodujo la dirección idéntica. La compensación es que cada operación Qi re-deriva desde cero en lugar de leer una caché, lo cual es más simple de razonar y no puede desviarse de lo que el mnemónico realmente implica, a costa de necesitar la contraseña más a menudo que el lado QUAI (ver abajo).

Por qué Qi necesita la contraseña con más frecuencia: el get_balance de QUAI lee el saldo de una cuenta pública directamente de la cadena — no se necesita ningún secreto. Qi no tiene tal cosa: un "saldo" es la suma de las salidas de transacciones no gastadas (UTXOs) que pertenecen a direcciones que solo el mnemónico de la cartera puede derivar, así que calcularlo en absoluto significa reconstruir la cartera primero. Por eso get_qi_balance requiere una contraseña (el get_balance de QUAI no la requiere), y por eso el paso de vista previa de convert_qi_to_quai puede cotizar una tasa de conversión pero no puede confirmar que realmente tienes suficiente Qi para gastar — esa comprobación solo ocurre cuando la contraseña llega al paso de confirmación.

Reglas de contraseña: mínimo 8 caracteres, comprobado antes de que se cifre nada. No hay una limitación de velocidad separada para intentos de contraseña incorrecta — los parámetros de coste de scrypt ya hacen que cada intento sea computacionalmente caro, que es la defensa estándar para este tipo de almacén de claves local.

Flujo de confirmación para send_transaction, convert_qi_to_quai y send_qi: los tres requieren siempre dos llamadas, y solo la segunda necesita la contraseña.

1. Llama con el destino y el importe (walletName/to/amount para send_transaction; walletName/recipientPaymentCode/amount/destinationZone para send_qi; la versión con forma de to para convert_qi_to_quai) — aún no se requiere contraseña. No se transmite nada. Recibes una vista previa — zonas resueltas, una estimación donde existe (gas para un envío, importe convertido para una conversión; send_qi no tiene ninguna, ya que es una transferencia 1:1), y un confirmationToken válido durante 2 minutos.

2. Llama de nuevo con los mismos parámetros, más confirm: true, ese confirmationToken y la password de la cartera. Solo entonces se descifra la clave/mnemónico y la transacción se firma y envía realmente.

Un token es de un solo uso y está vinculado a los parámetros exactos previsualizados — si algo cambia, el token ha expirado, o ya se ha usado, el paso 2 falla con un error claro y vuelves a previsualizar. Esto funciona igual independientemente de si el propio cliente MCP tiene una interfaz de aprobación de herramientas, así que es una barrera real en lugar de depender de que el cliente la proporcione. Una contraseña incorrecta falla limpiamente (Incorrect password for wallet "...") sin revelar si el token/parámetros eran válidos por lo demás.

Intencionadamente no hay una herramienta export_wallet/"mostrar clave privada o mnemónico" — una vez que un secreto está en el almacén, la única salida a través de este servidor es firmar con él.

Conversión QUAI ↔ Qi ("swap"): Quai tiene una conversión nativa a nivel de protocolo entre sus dos libros de contabilidad — QUAI (basado en cuentas) y Qi (basado en UTXO, como Bitcoin) — con una tasa de cambio en cadena, no un DEX de terceros. get_conversion_rate cotiza en cualquier dirección, sin necesidad de cartera. Ambas direcciones de ejecución están ahora implementadas:

• QUAI → Qi: solo un send_transaction normal a una dirección del libro de Qi (p. ej. una de create_qi_wallet). La herramienta lo detecta automáticamente (isConversion: true en la vista previa) y muestra el Qi estimado recibido junto con la información habitual de gas/saldo.

• Qi → QUAI: convert_qi_to_quai, usando QiHDWallet.convertToQuai de quais internamente, siguiendo el mismo patrón de vista previa/confirmación/contraseña que send_transaction.

Envío Qi → Qi: las carteras Qi no se envían entre sí directamente a sus direcciones. En su lugar, cada cartera Qi tiene un código de pago BIP-47 reutilizable (get_qi_payment_code) — compártelo como compartirías una dirección, pero se deriva de él una dirección de un solo uso nueva para cada pago, por privacidad. Para enviar, el remitente "abre un canal" con el código de pago del destinatario (send_qi lo hace automáticamente) — esto es ECDH local puro entre los dos códigos de pago, determinista y reproducible, sin acción en cadena ni estado persistente implicado. El inconveniente está en el extremo receptor: esas direcciones derivadas por pares no forman parte de la secuencia de direcciones determinista normal de la cartera, así que nada encontrará los fondos enviados de esa manera a menos que le digas que busque. Concretamente: después de que alguien pague a tu cartera Qi mediante código de pago, pasa su código de pago al parámetro counterpartyPaymentCodes de get_qi_balance — abre ese mismo canal y lo incluye en el saldo. No hay mecanismo de notificación (en cadena o de otro tipo) que diga al receptor que ha llegado un pago por código de pago; los dos lados tienen que conocerse ya fuera de banda, igual que necesitarías saber una dirección antes de comprobar su saldo. send_qi también admite envíos entre zonas (un destinationZone separado de la propia zona del remitente), igual que el ETX de send_transaction y el propio modelo de zonas de QiHDWallet.

Un borde áspero conocido: el paso de vista previa de send_qi no valida el formato del código de pago por adelantado (no hay un validador exportado para comprobarlo), así que un código malformado se previsualizará bien y solo fallará al confirmar — de forma segura (no se envía nada, no hay fondos en riesgo), solo más tarde de lo ideal.

Aún no implementado: deploy_contract, request_faucet.

Honestidad sobre lo que se ha probado aquí, actualizado: el bucle completo de send_qi / código de pago se verificó en vivo contra mainnet con dos carteras reales — se generó un código de pago BIP-47 real y correctamente formateado (PM8T...) y se confirmó que era determinista entre llamadas, una vista previa detectó correctamente entre zonas vs. misma zona, una confirmación contra una cartera vacía falló con un error genuino del SDK (No Qi available in zone) en lugar de bloquearse, y get_qi_balance aisló correctamente un código de pago de contraparte inválido en rejectedPaymentCodes sin hacer fallar toda la llamada. Lo que sigue sin verificar, por la misma razón que en todas partes de este documento: un envío real por código de pago completado entre dos carteras con fondos, ya que eso necesita Qi real y no se hizo sin que se pidiera.

Honestidad sobre lo que se ha probado aquí: todo lo anterior se ejercitó contra mainnet en vivo, incluyendo una comprobación de determinismo (exportar el mnemónico de una cartera Qi y reimportarlo con un nombre diferente reprodujo la dirección idéntica) y rutas de error reales (contraseña incorrecta, gas QUAI insuficiente, y un error real de QiHDWallet -- No Qi available in zone -- al intentar convertir desde una cartera Qi vacía). Lo que no se ha ejercitado es un convert_qi_to_quai o una conversión QUAI→Qi que realmente se complete contra una cartera que tenga fondos reales, ya que eso requiere gastar dinero real y no se hizo sin que se pidiera.

Instalación

npm install
npm run build

O ejecútalo directamente sin instalar, una vez publicado:

npx quai-mcp-server

Requisitos

• Node.js 18+

Configuración (variables de entorno)

Todas opcionales — los valores predeterminados sensatos apuntan a mainnet de Quai.

Cada herramienta también acepta un argumento network ("mainnet" o "testnet") por llamada, así que un cliente puede consultar cualquiera de las dos redes sin reiniciar el servidor.

Sobre las claves: ver "Carteras" arriba. Las claves solo existen como texto plano en memoria durante la duración de una llamada create_wallet/import_wallet/send_transaction que las necesite — nunca en disco, nunca registradas. Trata QUAI_WALLET_DIR (y la máquina que ejecute este servidor) como tratarías cualquier otro almacén de secretos local: cualquiera con acceso al sistema de archivos a ese directorio y suficiente computación para forzar por fuerza bruta una contraseña débil puede eventualmente descifrar una cartera, igual que un almacén de claves local de geth o una bóveda de MetaMask.

Registrarse con Claude Desktop

Añade esto a tu configuración MCP de Claude Desktop (claude_desktop_config.json — en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

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

O, si has clonado y compilado este repositorio localmente en lugar de usar un paquete publicado:

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

Para apuntarlo a testnet por defecto, añade un bloque env:

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

(luego pasa "network": "testnet" en llamadas de herramientas individuales — las variables de entorno establecen el endpoint, no la red predeterminada por llamada).

Registrarse con Claude Code

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

o, para una compilación local:

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

Desarrollo

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

El servidor habla MCP sobre stdio solo en v1; no hay transporte HTTP.

Notas de diseño

• quais sobre RPC crudo: cada herramienta pasa por JsonRpcProvider, Contract y las utilidades de direcciones del SDK quais en lugar de llamadas JSON-RPC eth_/quai_ hechas a mano, así que la resolución de zonas, el formato de las respuestas y las formas de los errores se mantienen consistentes con el resto del ecosistema Quai.

• Un proveedor, muchas zonas: un único JsonRpcProvider apuntado a una URL de puerta de enlace base (p. ej. https://rpc.quai.network) auto-descubre las zonas activas de la cadena Prime y enruta cada llamada a la correcta — la mayoría de las herramientas nunca construyen una URL por zona.

• Custodia, hecha con herramientas estándar, no criptografía personalizada: las carteras se almacenan usando la implementación de quais del formato de almacén de claves V3 de Ethereum (scrypt + AES-128-CTR + MAC) — el mismo esquema bien revisado que usan geth y MetaMask — en lugar de algo hecho a mano. Ver "Carteras" arriba para el modelo completo.

• Los errores son texto, no trazas de pila: los errores RPC/contrato se capturan y se reescriben en mensajes cortos y específicos (p. ej. "Contract call reverted: ...", "Insufficient funds: ...", "Incorrect password for wallet...", "not a validly checksummed Quai address") en lugar de filtrar objetos de excepción crudos al modelo.

• La confirmación es una barrera real, no solo una pista del cliente: las herramientas de escritura están anotadas con readOnlyHint: false (y destructiveHint: true para envíos) para que los clientes MCP con su propia interfaz de aprobación muestren una, pero send_transaction además impone su propio protocolo de vista previa → token → contraseña en el lado del servidor (src/confirmations.ts para el token, src/walletStore.ts + decryptKeystoreJson para la contraseña), así que sigue siendo seguro llamarlo desde un cliente sin interfaz de aprobación en absoluto.

• La contraseña solo se necesita una vez, en el último momento: previsualizar un envío resuelve la dirección de la cartera directamente de la parte no cifrada de su archivo de almacén de claves y usa un VoidSigner (un firmante de quais que puede estimar gas pero no firmar) para estimar el coste — sin descifrado, sin contraseña. Solo la llamada final de confirm: true descifra la clave, y solo durante la duración de esa única llamada.

• ETX no es una ruta de código separada: enviar a una dirección en una zona diferente usa exactamente la misma llamada send_transaction que un envío dentro de la misma zona — la red de Quai maneja el enrutamiento entre zonas (como transacción externa) de forma transparente una vez que la transacción firmada llega a la zona del remitente. La herramienta solo detecta e informa de las zonas implicadas para que quien llama sepa qué esperar.

• Las carteras Qi son sin estado entre llamadas, a propósito: create_qi_wallet/import_qi_wallet solo cifran un mnemónico. get_qi_balance y convert_qi_to_quai reconstruyen el QiHDWallet desde cero en cada llamada y re-derivan su dirección (src/qiWallet.ts) en lugar de leer cualquier estado de dirección/UTXO en caché — no hay ninguno que leer. Esto cambió un poco de rendimiento (cada operación Qi re-deriva y re-consulta en lugar de usar una caché) por una historia de seguridad más simple y más difícil de equivocar: lo único que está en reposo es el único secreto que importa.