Hyperlane MCP Server

Se integra con el protocolo Hyperlane para mensajería entre cadenas e interacciones con contratos inteligentes.

Documentación

Hyperlane MCP Server

Un potente servidor de Model Context Protocol (MCP) que proporciona una integración perfecta con el protocolo Hyperlane, permitiendo a los asistentes de LLM interactuar con mensajería entre cadenas y contratos inteligentes a través de múltiples blockchains.

Descripción general

El Hyperlane MCP Server cierra la brecha entre los asistentes de LLM y la infraestructura entre cadenas de Hyperlane. Proporciona una interfaz estandarizada para implementar cadenas, gestionar validadores y relayer, enviar mensajes entre cadenas y desplegar rutas warp para transferencias de activos.

Cómo funciona

Arquitectura

El servidor opera como un servidor MCP (Model Context Protocol) que:

Se conecta a múltiples blockchains: Utiliza el MultiProvider de Hyperlane para gestionar conexiones a varias redes blockchain.
Gestiona un registro local: Mantiene una caché local de metadatos de cadenas, contratos desplegados y configuraciones de rutas warp.
Despliega infraestructura: Maneja el despliegue de contratos principales de Hyperlane, validadores y relayer.
Facilita operaciones entre cadenas: Permite el paso de mensajes y transferencias de activos entre cadenas.
Proporciona integración con Docker: Ejecuta validadores y relayer en contenedores Docker para aislamiento.

Componentes principales

LocalRegistry: Extiende el sistema de registro de Hyperlane con capacidades de almacenamiento local.
HyperlaneDeployer: Maneja el despliegue de los contratos principales de Hyperlane.
ValidatorRunner: Gestiona los contenedores Docker de los validadores.
RelayerRunner: Gestiona los contenedores Docker de los relayer.
WarpRoute: Maneja el despliegue y la gestión de rutas de activos entre cadenas.

Características

Mensajería entre cadenas

Enviar mensajes entre diferentes redes blockchain.
Monitorear el estado de entrega de mensajes.
Manejar la verificación y ejecución de mensajes.

Despliegue y gestión de contratos

Desplegar contratos principales de Hyperlane en nuevas cadenas.
Desplegar y configurar rutas warp para transferencias de activos.
Gestionar configuraciones y actualizaciones de contratos.

Gestión de infraestructura

Ejecutar validadores para la verificación de mensajes.
Ejecutar relayer para la entrega de mensajes.
Monitorear la salud de validadores y relayer.
Manejar el ciclo de vida de los contenedores Docker.

Transferencias de activos

Desplegar rutas warp para transferencias de activos entre cadenas.
Ejecutar transferencias de activos de múltiples saltos.
Soporte para varios tipos de tokens (nativos, sintéticos, colaterales, etc.).

Requisitos

Requisitos del sistema

Node.js: v18 o superior.
Gestor de paquetes: pnpm (recomendado).
Docker: Para ejecutar validadores y relayer.
Sistema operativo: Linux, macOS o Windows con WSL2.

Requisitos de red

Acceso a endpoints RPC para las redes blockchain objetivo.
Conexión a internet estable para operaciones entre cadenas.
Ancho de banda suficiente para descargas de imágenes Docker.

Requisitos de blockchain

Clave privada con suficientes tokens nativos para tarifas de gas.
Acceso a endpoints RPC de blockchain.
Comprensión de las configuraciones de las cadenas objetivo.

Instalación y configuración

1. Clonar el repositorio

git clone https://github.com/yourusername/hyperlane-mcp.git
cd hyperlane-mcp

2. Instalar dependencias

# Install pnpm if not already installed
npm install -g pnpm

# Install project dependencies
pnpm install

3. Compilar el proyecto

pnpm build

4. Configurar variables de entorno

Crea un archivo .env en la raíz del proyecto:

cp .env.example .env

Edita el archivo .env con tu configuración:

# Required: Private key for signing transactions (without 0x prefix)
PRIVATE_KEY=your_private_key_here

# Required: GitHub Personal Access Token for registry access
GITHUB_TOKEN=your_github_personal_access_token

# Optional: Custom cache directory (defaults to ~/.hyperlane-mcp)
CACHE_DIR=/path/to/custom/cache/directory

5. Verificar la instalación de Docker

# Ensure Docker is running
docker --version
docker ps

Configuración

Variables de entorno

Variable	Requerida	Descripción	Valor por defecto
`PRIVATE_KEY`	Sí	Clave privada para firmar transacciones (sin prefijo 0x)	Ninguna
`GITHUB_TOKEN`	Sí	PAT de GitHub para acceder al registro de Hyperlane	Ninguna
`CACHE_DIR`	No	Directorio para almacenar datos locales	`~/.hyperlane-mcp`
`HOME`	No	Directorio de inicio (respaldo para CACHE_DIR)	Predeterminado del sistema

Configuración del cliente MCP

Para Claude Desktop u otros clientes MCP, agrega esta configuración:

{
  "mcpServers": {
    "hyperlane": {
      "command": "node",
      "args": [
        "/path/to/hyperlane-mcp/build/index.js"
      ],
      "env": {
        "PRIVATE_KEY": "your_private_key",
        "GITHUB_TOKEN": "your_github_token"
        "CACHE_DIR": "your_cache_dir"
      }
    }
  }
}

Uso

Iniciar el servidor

# Development mode
pnpm start

# Production mode
node build/index.js

# With MCP Inspector (for debugging)
pnpm inspect

Flujo de trabajo básico

Desplegar una nueva cadena: Usa la herramienta deploy-chain para agregar una nueva blockchain.
Ejecutar validador: Usa run-validator para iniciar la validación de mensajes.
Ejecutar relayer: Usa run-relayer para habilitar la entrega de mensajes.
Desplegar ruta warp: Usa deploy-warp-route para transferencias de activos.
Enviar mensajes/activos: Usa las herramientas de transferencia para operaciones entre cadenas.

Herramientas disponibles

Gestión de cadenas

deploy-chain: Desplegar contratos principales de Hyperlane en una nueva cadena.
run-validator: Iniciar un validador para una cadena específica.
run-relayer: Iniciar un relayer para la entrega de mensajes entre cadenas.

Operaciones entre cadenas

cross-chain-message-transfer: Enviar mensajes entre cadenas.
cross-chain-asset-transfer: Transferir activos usando rutas warp.

Gestión de rutas warp

deploy-warp-route: Desplegar nuevas rutas warp para transferencias de activos.

Recursos

Configuraciones de rutas warp: Acceso a través del URI hyperlane-warp:///{symbol}/{/chain*}.

Estructura del proyecto

hyperlane-mcp/
├── src/                          # Source code
│   ├── index.ts                  # Main MCP server entry point
│   ├── localRegistry.ts          # Local registry implementation
│   ├── hyperlaneDeployer.ts      # Core contract deployment
│   ├── RunValidator.ts           # Validator Docker management
│   ├── RunRelayer.ts             # Relayer Docker management
│   ├── warpRoute.ts              # Warp route deployment
│   ├── msgTransfer.ts            # Message transfer logic
│   ├── assetTransfer.ts          # Asset transfer logic
│   ├── config.ts                 # Configuration utilities
│   ├── utils.ts                  # Utility functions
│   ├── types.ts                  # Type definitions
│   ├── logger.ts                 # Logging configuration
│   ├── gcr.ts                    # Google Container Registry utilities
│   ├── file.ts                   # File system utilities
│   ├── configOpts.ts             # Configuration options
│   └── consts.ts                 # Constants
├── build/                        # Compiled JavaScript output
├── node_modules/                 # Dependencies
├── package.json                  # Project configuration
├── tsconfig.json                 # TypeScript configuration
├── .env                          # Environment variables (create this)
└── README.md                     # This file

Archivos y carpetas creados

El servidor crea y gestiona varios directorios y archivos durante su operación:

Estructura del directorio de caché

~/.hyperlane-mcp/                 # Main cache directory
├── chains/                       # Chain configurations
│   ├── {chainName}.yaml          # Chain metadata
│   ├── {chainName}.deploy.yaml   # Deployed contract addresses
│   └── {chainName}-core-config.yaml # Core deployment config
├── routes/                       # Warp route configurations
│   └── {symbol}-{hash}.yaml      # Warp route configs
├── agents/                       # Agent configurations
│   └── {chainName}-agent-config.json # Validator/relayer configs
└── logs/                         # Runtime data and logs
    ├── hyperlane_db_validator_{chain}/ # Validator database
    ├── hyperlane_db_relayer/     # Relayer database
    └── hyperlane-validator-signatures-{chain}/ # Validator signatures

Tipos de archivos creados

Archivos de configuración de cadenas

{chainName}.yaml: Contiene metadatos de la cadena (URLs RPC, ID de cadena, información del token nativo).
{chainName}.deploy.yaml: Direcciones de contratos desplegados (mailbox, ISM, hooks, etc.).
{chainName}-core-config.yaml: Configuración principal del despliegue.

Archivos de rutas warp

{symbol}-{hash}.yaml: Configuración de rutas warp para transferencias de activos entre cadenas.

Archivos de configuración de agentes

{chainName}-agent-config.json: Configuración para validadores y relayer.

Volúmenes Docker

Bases de datos de validadores: Almacenamiento persistente para el estado del validador.
Bases de datos de relayer: Almacenamiento persistente para el estado del relayer.
Almacenamiento de firmas: Firmas de puntos de control del validador.

Archivos temporales

Contenedores Docker: Contenedores de validadores y relayer (gestionados automáticamente).
Archivos de registro: Registros de ejecución de validadores y relayer.

Ejemplos

1. Desplegar una nueva cadena

Deploy Hyperlane core contracts to a new blockchain called "mytestnet" with chain ID 12345, RPC URL "https://rpc.mytestnet.com", native token symbol "MTN", and token name "MyTestNet Token". This should be marked as a testnet.

2. Enviar mensaje entre cadenas

Send a cross-chain message from Ethereum to Polygon. The recipient address should be 0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6 and the message body should be "Hello from Ethereum!"

3. Desplegar ruta warp

Deploy a warp route for asset transfers between Ethereum and Arbitrum chains. Use collateral token type for Ethereum and synthetic token type for Arbitrum.

4. Transferir activos

Transfer assets using the USDC warp route from Ethereum to Arbitrum. Transfer 100 USDC to recipient address 0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6. First, fetch the warp route configuration for USDC on these chains using the resources.

5. Ejecutar infraestructura

Start a validator for the "mytestnet" chain that we deployed earlier.

Start a relayer to handle message delivery between Ethereum and mytestnet chains. Use "mytestnet" as the validator chain name.

6. Transferencia de activos entre múltiples cadenas

Transfer 50 USDC from Ethereum to Polygon, then from Polygon to Arbitrum, using the existing USDC warp routes. The final recipient should be 0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6.

7. Verificar recursos de rutas warp

Show me the available warp route configurations for USDC token across Ethereum and Polygon chains.

8. Desplegar ruta de token personalizado

Deploy a new warp route for a custom token called "MyToken" (symbol: MTK) between three chains: Ethereum (collateral type), Polygon (synthetic type), and Arbitrum (synthetic type).

Solución de problemas

Problemas comunes

1. Errores de permisos de Docker

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Restart shell or logout/login

2. Tarifas de gas insuficientes

Asegúrate de que tu billetera tenga suficientes tokens nativos para el gas.
Verifica los precios de gas actuales en las redes objetivo.

3. Problemas de conexión RPC

Verifica que las URLs RPC sean accesibles.
Comprueba si hay límites de velocidad en los proveedores RPC.
Considera usar múltiples endpoints RPC.

4. Fallos al iniciar contenedores

# Check Docker logs
docker logs <container_id>

# Verify Docker image availability
docker pull gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.4.0

Modo de depuración

Ejecuta con MCP Inspector para una depuración detallada:

pnpm inspect

Archivos de registro

Revisa los registros en el directorio de caché:

# Validator logs
tail -f ~/.hyperlane-mcp/logs/validator-{chain}.log

# Relayer logs  
tail -f ~/.hyperlane-mcp/logs/relayer.log

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Configuración de desarrollo

Haz un fork del repositorio.
Crea una rama de características.
Realiza tus cambios.
Agrega pruebas si corresponde.
Envía un pull request.

Estilo de código

Usa TypeScript para todo el código nuevo.
Sigue el formato de código existente (Prettier).
Agrega comentarios JSDoc para las APIs públicas.
Incluye manejo de errores.

Autores

Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Aviso legal

El software se proporciona tal cual. No se ofrece ninguna garantía, representación o garantía, expresa o implícita, sobre la seguridad o corrección del software. No ha sido auditado y, por lo tanto, no se puede asegurar que funcione como se espera. Los usuarios pueden experimentar retrasos, fallos, errores, omisiones, pérdida de información transmitida o pérdida de fondos. Los creadores no son responsables de lo anterior. Los usuarios deben proceder con precaución y usarlo bajo su propio riesgo.