MCP-ABI

Interactúa con contratos inteligentes compatibles con Ethereum usando su ABI.

Documentación

🔗 Servidor MCP ABI

📖 Descripción general

El servidor MCP ABI permite a los agentes de IA interactuar con cualquier contrato inteligente compatible con Ethereum utilizando su ABI (Interfaz Binaria de Aplicaciones). Este servidor genera dinámicamente herramientas MCP a partir de los ABIs de los contratos, permitiendo una interacción fluida con cualquier contrato inteligente sin necesidad de implementaciones de herramientas personalizadas.

Al implementar el Protocolo de Contexto de Modelos (MCP), este servidor permite que los Modelos de Lenguaje de Gran Tamaño (LLMs) lean el estado del contrato, ejecuten transacciones e interactúen con aplicaciones descentralizadas directamente a través de su ventana de contexto.

✨ Características

Generación Dinámica de Herramientas: Crea automáticamente herramientas MCP a partir de cualquier ABI de contrato en tiempo de ejecución.
Funciones de Lectura: Consulta el estado del contrato (funciones view/pure) sin enviar transacciones.
Funciones de Escritura: Ejecuta transacciones que modifican el estado con soporte de firma de cartera.
Soporte Multi-Cadena: Funciona con cualquier blockchain compatible con EVM mediante endpoints RPC configurables.
Interacciones con Seguridad de Tipos: Valida los argumentos de las funciones contra las especificaciones del ABI.

📦 Instalación

🚀 Usando npx (Recomendado)

Para usar este servidor sin instalarlo globalmente:

npx @iqai/mcp-abi

🔧 Compilar desde el Código Fuente

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

⚡ Ejecución con un Cliente MCP

Agrega la siguiente configuración a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json).

📋 Configuración 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"
      }
    }
  }
}

⚙️ Configuración Avanzada (Compilación 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"
      }
    }
  }
}

🔐 Configuración (Variables de Entorno)

Variable	Requerida	Descripción	Valor Predeterminado
`CONTRACT_ABI`	Sí	Representación en cadena JSON del ABI del contrato	-
`CONTRACT_ADDRESS`	Sí	La dirección del contrato desplegado en la blockchain	-
`CONTRACT_NAME`	No	Nombre amigable para el contrato (se usa como prefijo del nombre de la herramienta)	`CONTRACT`
`WALLET_PRIVATE_KEY`	Para escrituras	Clave privada para firmar transacciones (requerida para funciones de escritura)	-
`CHAIN_ID`	No	ID de cadena de la red blockchain	`252` (Fraxtal)
`RPC_URL`	No	URL del endpoint RPC personalizado	Predeterminado para la cadena

💡 Ejemplos de Uso

🔍 Leer Estado del Contrato

"Verifica el saldo de tokens de la cartera 0xabc..."
"¿Cuál es el suministro total de este token?"
"Obtén la asignación para el gastador 0x123... del propietario 0x456..."

📝 Ejecutar Transacciones

"Transfiere 100 tokens a la dirección 0xabc..."
"Aprueba a 0x123... para gastar 1000 tokens"
"Acuña un nuevo NFT a la cartera 0xdef..."

📊 Análisis de Contratos

"¿Qué funciones están disponibles en este contrato?"
"Muéstrame todas las funciones de lectura que puedo llamar"
"¿Qué parámetros requiere la función de transferencia?"

🛠️ Herramientas MCP

Las herramientas se generan dinámicamente según el ABI del contrato proporcionado. Cada función en el ABI se convierte en una herramienta MCP:

Funciones de Lectura (view/pure): Herramientas con prefijo del nombre del contrato (por ejemplo, erc20_balanceOf, erc20_totalSupply)
Funciones de Escritura: Herramientas para operaciones que modifican el estado (por ejemplo, erc20_transfer, erc20_approve)

Ejemplo de nombres de herramientas para un contrato ERC20 con CONTRACT_NAME=ERC20:

erc20_balanceOf - Consultar saldo de tokens
erc20_transfer - Transferir tokens
erc20_approve - Aprobar gasto
erc20_allowance - Verificar asignación

Nota: Las herramientas se generan dinámicamente según el ABI del contrato cargado. Los nombres de las herramientas siguen el patrón {contractname}_{functionname}.

Generación Dinámica de Herramientas

Cuando cargas un ABI de contrato, se crean automáticamente herramientas para cada función en el ABI:

Funciones de lectura se convierten en herramientas de consulta (sin requerir gas)
Funciones de escritura se convierten en herramientas de ejecución (requieren cartera)

Parámetros Comunes

Todas las herramientas generadas aceptan el mismo esquema de parámetros:

Parámetro	Tipo	Requerido	Valor Predeterminado	Descripción
`args`	array	No	`[]`	Argumentos de la función como un array. Ejemplo: `["0x123...", 100, true]`

Ejemplo de Herramientas Generadas

Si cargas un contrato de token ERC-20 llamado "USDC", se generarían las siguientes herramientas:

usdc_name - Consultar el nombre del token
usdc_symbol - Consultar el símbolo del token
usdc_decimals - Consultar los decimales del token
usdc_totalSupply - Consultar el suministro total de tokens
usdc_balanceOf - Consultar el saldo de una dirección
usdc_transfer - Transferir tokens a una dirección
usdc_approve - Aprobar asignación de gasto
usdc_transferFrom - Transferir tokens en nombre de otra dirección

Formato de Respuesta de las Herramientas

Funciones de Lectura:

✅ Successfully queried {functionName}

📊 Result:
{JSON result}

Funciones de Escritura:

✅ Successfully executed {functionName}

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

👨‍💻 Desarrollo

🏗️ Compilar Proyecto

pnpm run build

👁️ Modo de Desarrollo (Vigilancia)

pnpm run watch

✅ Linting y Formato

pnpm run lint
pnpm run format

📁 Estructura del Proyecto

src/tools/: Lógica de generación de herramientas
src/services/: Servicio de interacción con contratos
src/lib/: Utilidades compartidas
src/index.ts: Punto de entrada del servidor

📚 Recursos

⚠️ Aviso Legal

Esta herramienta interactúa con contratos inteligentes de blockchain y puede ejecutar transacciones reales. Almacena las claves privadas de forma segura y nunca las comprometas en el control de versiones. Siempre prueba las interacciones en testnets antes del despliegue en mainnet. El comercio y la interacción con contratos inteligentes implican riesgo.

📄 Licencia

ISC