MCP-ABI

Interaja com contratos inteligentes compatíveis com Ethereum usando sua ABI.

Documentação

🔗 Servidor MCP ABI

📖 Visão Geral

O Servidor MCP ABI permite que agentes de IA interajam com qualquer contrato inteligente compatível com Ethereum usando sua ABI (Interface Binária de Aplicação). Este servidor gera dinamicamente ferramentas MCP a partir das ABIs dos contratos, permitindo interação perfeita com qualquer contrato inteligente sem exigir implementações de ferramentas personalizadas.

Ao implementar o Protocolo de Contexto de Modelo (MCP), este servidor permite que Modelos de Linguagem de Grande Porte (LLMs) leiam o estado do contrato, executem transações e interajam com aplicações descentralizadas diretamente através de sua janela de contexto.

✨ Recursos

Geração Dinâmica de Ferramentas: Cria automaticamente ferramentas MCP a partir de qualquer ABI de contrato em tempo de execução.
Funções de Leitura: Consulta o estado do contrato (funções view/pure) sem enviar transações.
Funções de Escrita: Executa transações que alteram o estado com suporte a assinatura de carteira.
Suporte a Múltiplas Cadeias: Funciona com qualquer blockchain compatível com EVM através de endpoints RPC configuráveis.
Interações Type-Safe: Valida argumentos de funções de acordo com as especificações da ABI.

📦 Instalação

🚀 Usando npx (Recomendado)

Para usar este servidor sem instalá-lo globalmente:

npx @iqai/mcp-abi

🔧 Compilar a partir do Código Fonte

git clone https://github.com/IQAIcom/mcp-abi.git
cd mcp-abi
pnpm install
pnpm run build

⚡ Executando com um Cliente MCP

Adicione a seguinte configuração às configurações do seu cliente MCP (ex.: claude_desktop_config.json).

📋 Configuração Mínima

{
  "mcpServers": {
    "smart-contract-abi": {
      "command": "npx",
      "args": ["-y", "@iqai/mcp-abi"],
      "env": {
        "CONTRACT_ABI": "[{\"inputs\":[{\"name\":\"account\",\"type\":\"address\"}],\"name\":\"balanceOf\",\"outputs\":[{\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"}]",
        "CONTRACT_ADDRESS": "0xaB195B090Cc60C1EFd4d1cEE94Bf441F5931C01b",
        "CONTRACT_NAME": "ERC20"
      }
    }
  }
}

⚙️ Configuração Avançada (Compilação Local)

{
  "mcpServers": {
    "smart-contract-abi": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-abi/dist/index.js"],
      "env": {
        "WALLET_PRIVATE_KEY": "your_wallet_private_key_here",
        "CONTRACT_ABI": "[{\"inputs\":[{\"name\":\"to\",\"type\":\"address\"},{\"name\":\"amount\",\"type\":\"uint256\"}],\"name\":\"transfer\",\"outputs\":[{\"type\":\"bool\"}],\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]",
        "CONTRACT_ADDRESS": "0xaB195B090Cc60C1EFd4d1cEE94Bf441F5931C01b",
        "CONTRACT_NAME": "ERC20",
        "CHAIN_ID": "252",
        "RPC_URL": "https://rpc.frax.com"
      }
    }
  }
}

🔐 Configuração (Variáveis de Ambiente)

Variável	Obrigatória	Descrição	Padrão
`CONTRACT_ABI`	Sim	Representação em string JSON da ABI do contrato	-
`CONTRACT_ADDRESS`	Sim	Endereço do contrato implantado na blockchain	-
`CONTRACT_NAME`	Não	Nome amigável para o contrato (usado como prefixo do nome da ferramenta)	`CONTRACT`
`WALLET_PRIVATE_KEY`	Para escritas	Chave privada para assinar transações (necessária para funções de escrita)	-
`CHAIN_ID`	Não	ID da cadeia da rede blockchain	`252` (Fraxtal)
`RPC_URL`	Não	URL do endpoint RPC personalizado	Padrão para a cadeia

💡 Exemplos de Uso

🔍 Ler Estado do Contrato

"Verifique o saldo de tokens da carteira 0xabc..."
"Qual é o fornecimento total deste token?"
"Obtenha a permissão para o gastador 0x123... do proprietário 0x456..."

📝 Executar Transações

"Transfira 100 tokens para o endereço 0xabc..."
"Aprove 0x123... para gastar 1000 tokens"
"Cunhe um novo NFT para a carteira 0xdef..."

📊 Análise de Contrato

"Quais funções estão disponíveis neste contrato?"
"Mostre-me todas as funções de leitura que posso chamar"
"Quais parâmetros a função de transferência exige?"

🛠️ Ferramentas MCP

As ferramentas são geradas dinamicamente com base na ABI do contrato fornecida. Cada função na ABI se torna uma ferramenta MCP:

Funções de Leitura (view/pure): Ferramentas prefixadas com o nome do contrato (ex.: erc20_balanceOf, erc20_totalSupply)
Funções de Escrita: Ferramentas para operações que alteram o estado (ex.: erc20_transfer, erc20_approve)

Exemplo de nomes de ferramentas para um contrato ERC20 com CONTRACT_NAME=ERC20:

erc20_balanceOf - Consultar saldo de tokens
erc20_transfer - Transferir tokens
erc20_approve - Aprovar gastos
erc20_allowance - Verificar permissão

Nota: As ferramentas são geradas dinamicamente com base na ABI do contrato carregada. Os nomes das ferramentas seguem o padrão {contractname}_{functionname}.

Geração Dinâmica de Ferramentas

Quando você carrega uma ABI de contrato, as ferramentas são criadas automaticamente para cada função na ABI:

Funções de leitura tornam-se ferramentas de consulta (sem necessidade de gás)
Funções de escrita tornam-se ferramentas de execução (exige carteira)

Parâmetros Comuns

Todas as ferramentas geradas aceitam o mesmo esquema de parâmetros:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`args`	array	Não	`[]`	Argumentos da função como um array. Exemplo: `["0x123...", 100, true]`

Exemplo de Ferramentas Geradas

Se você carregar um contrato de token ERC-20 chamado "USDC", as seguintes ferramentas seriam geradas:

usdc_name - Consultar o nome do token
usdc_symbol - Consultar o símbolo do token
usdc_decimals - Consultar as casas decimais do token
usdc_totalSupply - Consultar o fornecimento total de tokens
usdc_balanceOf - Consultar o saldo de um endereço
usdc_transfer - Transferir tokens para um endereço
usdc_approve - Aprovar permissão de gastos
usdc_transferFrom - Transferir tokens em nome de outro endereço

Formato de Resposta das Ferramentas

Funções de Leitura:

✅ Successfully queried {functionName}

📊 Result:
{JSON result}

Funções de Escrita:

✅ Successfully executed {functionName}

🔗 Transaction Hash: {hash}
📦 Block Number: {blockNumber}
⛽ Gas Used: {gasUsed}
✅ Status: Success

👨‍💻 Desenvolvimento

🏗️ Compilar Projeto

pnpm run build

👁️ Modo de Desenvolvimento (Watch)

pnpm run watch

✅ Lint e Formatação

pnpm run lint
pnpm run format

📁 Estrutura do Projeto

src/tools/: Lógica de geração de ferramentas
src/services/: Serviço de interação com contratos
src/lib/: Utilitários compartilhados
src/index.ts: Ponto de entrada do servidor

📚 Recursos

⚠️ Aviso Legal

Esta ferramenta interage com contratos inteligentes de blockchain e pode executar transações reais. Armazene chaves privadas com segurança e nunca as envie para controle de versão. Sempre teste interações em testnets antes da implantação na mainnet. Negociar e interagir com contratos inteligentes envolve risco.

📄 Licença

ISC