Hyperlane MCP Server

Integra-se ao protocolo Hyperlane para mensagens entre cadeias e interações com contratos inteligentes.

Documentação

Servidor MCP Hyperlane

Um poderoso servidor Model Context Protocol (MCP) que fornece integração perfeita com o protocolo Hyperlane, permitindo que assistentes de LLM interajam com mensagens entre cadeias e contratos inteligentes em múltiplas blockchains.

Visão Geral

O Servidor MCP Hyperlane preenche a lacuna entre assistentes de LLM e a infraestrutura entre cadeias da Hyperlane. Ele fornece uma interface padronizada para implantar cadeias, gerenciar validadores e relayers, enviar mensagens entre cadeias e implantar rotas de warp para transferências de ativos.

Como Funciona

Arquitetura

O servidor opera como um servidor MCP (Model Context Protocol) que:

Conecta-se a Múltiplas Blockchains: Usa o MultiProvider da Hyperlane para gerenciar conexões com várias redes blockchain
Gerencia Registro Local: Mantém um cache local de metadados de cadeias, contratos implantados e configurações de rotas de warp
Implanta Infraestrutura: Lida com a implantação de contratos principais da Hyperlane, validadores e relayers
Facilita Operações Entre Cadeias: Permite passagem de mensagens e transferências de ativos entre cadeias
Fornece Integração com Docker: Executa validadores e relayers em contêineres Docker para isolamento

Componentes Principais

LocalRegistry: Estende o sistema de registro da Hyperlane com capacidades de armazenamento local
HyperlaneDeployer: Lida com a implantação dos contratos principais da Hyperlane
ValidatorRunner: Gerencia contêineres Docker de validadores
RelayerRunner: Gerencia contêineres Docker de relayers
WarpRoute: Lida com a implantação e gerenciamento de rotas de ativos entre cadeias

Recursos

Mensagens Entre Cadeias

Enviar mensagens entre diferentes redes blockchain
Monitorar o status de entrega de mensagens
Lidar com verificação e execução de mensagens

Implantação e Gerenciamento de Contratos

Implantar contratos principais da Hyperlane em novas cadeias
Implantar e configurar rotas de warp para transferências de ativos
Gerenciar configurações e atualizações de contratos

Gerenciamento de Infraestrutura

Executar validadores para verificação de mensagens
Executar relayers para entrega de mensagens
Monitorar a saúde de validadores e relayers
Lidar com o ciclo de vida de contêineres Docker

Transferências de Ativos

Implantar rotas de warp para transferências de ativos entre cadeias
Executar transferências de ativos com múltiplos saltos
Suportar vários tipos de tokens (nativos, sintéticos, colaterais, etc.)

Requisitos

Requisitos do Sistema

Node.js: v18 ou superior
Gerenciador de Pacotes: pnpm (recomendado)
Docker: Para executar validadores e relayers
Sistema Operacional: Linux, macOS ou Windows com WSL2

Requisitos de Rede

Acesso a endpoints RPC para redes blockchain alvo
Conexão estável com a internet para operações entre cadeias
Largura de banda suficiente para downloads de imagens Docker

Requisitos de Blockchain

Chave privada com tokens nativos suficientes para taxas de gás
Acesso a endpoints RPC de blockchain
Compreensão das configurações das cadeias alvo

Instalação e Configuração

1. Clone o Repositório

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

2. Instale as Dependências

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

# Install project dependencies
pnpm install

3. Compile o Projeto

pnpm build

4. Configure as Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

cp .env.example .env

Edite o arquivo .env com sua configuração:

# 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. Verifique a Instalação do Docker

# Ensure Docker is running
docker --version
docker ps

Configuração

Variáveis de Ambiente

Variável	Obrigatória	Descrição	Padrão
`PRIVATE_KEY`	Sim	Chave privada para assinatura de transações (sem prefixo 0x)	Nenhum
`GITHUB_TOKEN`	Sim	PAT do GitHub para acessar o registro da Hyperlane	Nenhum
`CACHE_DIR`	Não	Diretório para armazenar dados locais	`~/.hyperlane-mcp`
`HOME`	Não	Diretório inicial (fallback para CACHE_DIR)	Padrão do sistema

Configuração do Cliente MCP

Para o Claude Desktop ou outros clientes MCP, adicione esta configuração:

{
  "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

Iniciando o Servidor

# Development mode
pnpm start

# Production mode
node build/index.js

# With MCP Inspector (for debugging)
pnpm inspect

Fluxo de Trabalho Básico

Implante uma Nova Cadeia: Use a ferramenta deploy-chain para adicionar uma nova blockchain
Execute o Validador: Use run-validator para iniciar a validação de mensagens
Execute o Relayer: Use run-relayer para habilitar a entrega de mensagens
Implante Rota de Warp: Use deploy-warp-route para transferências de ativos
Envie Mensagens/Ativos: Use ferramentas de transferência para operações entre cadeias

Ferramentas Disponíveis

Gerenciamento de Cadeias

deploy-chain: Implanta contratos principais da Hyperlane em uma nova cadeia
run-validator: Inicia um validador para uma cadeia específica
run-relayer: Inicia um relayer para entrega de mensagens entre cadeias

Operações Entre Cadeias

cross-chain-message-transfer: Envia mensagens entre cadeias
cross-chain-asset-transfer: Transfere ativos usando rotas de warp

Gerenciamento de Rotas de Warp

deploy-warp-route: Implanta novas rotas de warp para transferências de ativos

Recursos

Configurações de Rotas de Warp: Acesse via URI hyperlane-warp:///{symbol}/{/chain*}

Estrutura do Projeto

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

Arquivos e Pastas Criados

O servidor cria e gerencia vários diretórios e arquivos durante a operação:

Estrutura do Diretório de Cache

~/.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 Arquivos Criados

Arquivos de Configuração de Cadeias

{chainName}.yaml: Contém metadados da cadeia (URLs RPC, ID da cadeia, informações do token nativo)
{chainName}.deploy.yaml: Endereços de contratos implantados (mailbox, ISM, hooks, etc.)
{chainName}-core-config.yaml: Configuração principal de implantação

Arquivos de Rotas de Warp

{symbol}-{hash}.yaml: Configuração de rota de warp para transferências de ativos entre cadeias

Arquivos de Configuração de Agentes

{chainName}-agent-config.json: Configuração para validadores e relayers

Volumes Docker

Bancos de dados de validadores: Armazenamento persistente para estado do validador
Bancos de dados de relayers: Armazenamento persistente para estado do relayer
Armazenamento de assinaturas: Assinaturas de checkpoint do validador

Arquivos Temporários

Contêineres Docker: Contêineres de validadores e relayers (gerenciados automaticamente)
Arquivos de log: Logs de execução de validadores e relayers

Exemplos

1. Implante uma Nova Cadeia

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. Envie Mensagem Entre Cadeias

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. Implante Rota de 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. Transfira Ativos

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. Execute Infraestrutura

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. Transferência de Ativos Multi-Cadeia

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. Verifique Recursos de Rotas de Warp

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

8. Implante Rota 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).

Solução de Problemas

Problemas Comuns

1. Erros de Permissão do Docker

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

2. Taxas de Gás Insuficientes

Certifique-se de que sua carteira tenha tokens nativos suficientes para gás
Verifique os preços atuais de gás nas redes alvo

3. Problemas de Conexão RPC

Verifique se as URLs RPC estão acessíveis
Verifique se há limitação de taxa nos provedores RPC
Considere usar múltiplos endpoints RPC

4. Falhas na Inicialização de Contêineres

# 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 Depuração

Execute com o MCP Inspector para depuração detalhada:

pnpm inspect

Arquivos de Log

Verifique os logs no diretório de cache:

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

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

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Configuração de Desenvolvimento

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Adicione testes se aplicável
Envie um pull request

Estilo de Código

Use TypeScript para todo código novo
Siga a formatação de código existente (Prettier)
Adicione comentários JSDoc para APIs públicas
Inclua tratamento de erros

Autores

Licença

Este projeto é licenciado sob a Licença MIT.

Aviso Legal

O software é fornecido como está. Nenhuma garantia, representação ou garantia está sendo feita, expressa ou implícita, quanto à segurança ou correção do software. Ele não foi auditado e, portanto, não há garantia de que funcionará como pretendido. Os usuários podem experimentar atrasos, falhas, erros, omissões, perda de informações transmitidas ou perda de fundos. Os criadores não são responsáveis por qualquer um dos itens acima. Os usuários devem proceder com cautela e usar por sua conta e risco.