Servidor MCP Neo N3

Un servidor MCP que proporciona una integración perfecta con la cadena de bloques Neo N3, lo que permite a Claude interactuar con los datos de la cadena de bloques, administrar billeteras, transferir activos e invocar contratos inteligentes.

📚 Documentación

Sitio web : sitio web completo con documentación, guías de usuario y ejemplos.
Referencia de API : documentación detallada de API para todas las herramientas y recursos
Guía de implementación : opciones de implementación y configuración completas
Guía de pruebas : Enfoque de prueba e instrucciones para verificar la funcionalidad
Arquitectura : decisiones detalladas sobre la arquitectura del sistema y el diseño
Arquitectura de red : compatibilidad con red dual y detalles de configuración
Configuración de red : configure qué redes (red principal, red de prueba o ambas) están habilitadas

🚀 Características

Compatibilidad con red dual : interactúe con las redes principales y de prueba de Neo N3 en un solo servidor
Información de blockchain : consulta la altura de la blockchain, los validadores y el estado de la red
Datos de bloques y transacciones : obtenga información detallada sobre bloques y transacciones
Gestión de cuentas : Consulta saldos, crea e importa billeteras de forma segura
Operaciones de activos : Transferencia de NEO, GAS y otros tokens entre direcciones
Interacción de contratos inteligentes : Implemente e invoque contratos inteligentes en la cadena de bloques Neo N3
Compatibilidad con contratos famosos : interactúe con NeoFS, NeoBurger, Flamingo, NeoCompound, GrandShare y GhostMarket
Monitoreo de transacciones : Verifique el estado detallado de las transacciones con seguimiento de confirmación
Estimación de tarifa de gas : Calcule las tarifas de gas estimadas para las transferencias antes de ejecutarlas
Comunicación RPC resiliente : mecanismos de reintento automático con retroceso exponencial
Centrado en la seguridad : validación de entrada, almacenamiento seguro de billetera y protección de claves privadas
Compatibilidad con Docker : Implementación sencilla con Docker y Docker Compose
Instalación con un solo clic : proceso de configuración sencillo para la integración de Claude

🔄 Novedades de la v1.0.8

Confiabilidad de RPC mejorada : uso de puntos finales HTTPS seguros para ambas redes:
- Red principal: https://mainnet1.neo.coz.io:443
- Red de prueba: https://testnet1.neo.coz.io:443
Sitio web completo : nuevo sitio web con documentación detallada, guías de usuario y ejemplos de integración
Herramientas de desarrollo mejoradas : se agregaron scripts de reconstrucción y compatibilidad con modo oscuro
Mejor documentación : organización y legibilidad mejoradas de la documentación

Configuración con MCP

Puede agregar fácilmente el servidor Neo N3 MCP a su configuración de Claude MCP de diferentes maneras:

Uso de NPM (recomendado para inicio rápido)

Agregue esto a su claude_desktop_config.json o configuración de MCP:

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": [
        "-y",
        "@r3e/neo-n3-mcp"
      ]
    }
  }
}

Esto descargará y ejecutará automáticamente el servidor Neo N3 MCP sin ninguna instalación local.

Usando Docker

Agregue esto a su claude_desktop_config.json o configuración de MCP:

{
  "mcpServers": {
    "neo-n3": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "r3e/neo-n3-mcp"
      ]
    }
  }
}

Para construir la imagen de Docker localmente:

docker build -t r3e/neo-n3-mcp .

Instalación

Usando Docker (recomendado)

# Clone the repository
git clone https://github.com/R3E-Network/neo-n3-mcp.git
cd neo-n3-mcp

# Start the server with Docker Compose
docker-compose up -d

Instalación manual

# Clone the repository
git clone https://github.com/R3E-Network/neo-n3-mcp.git
cd neo-n3-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Agregar a la configuración de MCP

Para agregar el servidor Neo N3 MCP a su configuración de MCP, puede usar el script proporcionado:

# Build the project first
npm run build

# Add to MCP settings
npm run add-to-mcp

Esto agregará automáticamente el servidor Neo N3 MCP a su archivo de configuración MCP de Claude, haciéndolo disponible para su uso con Claude.

Configuración

El servidor se puede configurar mediante variables de entorno:

NEO_RPC_URL : URL predeterminada del nodo RPC Neo N3 (predeterminado: https://mainnet1.neo.coz.io:443 )
NEO_MAINNET_RPC_URL : URL del nodo RPC de la red principal Neo N3 (predeterminado: igual que NEO_RPC_URL o https://mainnet1.neo.coz.io:443 )
NEO_TESTNET_RPC_URL : URL del nodo RPC de la red de prueba Neo N3 (predeterminado: https://testnet1.neo.coz.io:443 )
NEO_NETWORK : Tipo de red predeterminado: 'mainnet' o 'testnet' (predeterminado: mainnet)
NEO_NETWORK_MODE : Modo de red: 'mainnet_only', 'testnet_only' o 'both' (predeterminado: ambos)
WALLET_PATH : Ruta a los archivos de la billetera (predeterminado: ./wallets)
LOG_LEVEL : Nivel de registro: 'depuración', 'información', 'advertencia', 'error' (predeterminado: información)
LOG_CONSOLE : Si desea iniciar sesión en la consola (valor predeterminado: verdadero)
LOG_FILE : Si se debe registrar en un archivo (predeterminado: falso)
LOG_FILE_PATH : Ruta al archivo de registro (predeterminado: ./logs/neo-n3-mcp.log)
MAX_REQUESTS_PER_MINUTE : Número máximo de solicitudes por minuto (predeterminado: 60)
REQUIRE_CONFIRMATION : Si se requiere confirmación para operaciones sensibles (valor predeterminado: verdadero)

Uso

Herramientas de configuración de red

El servidor proporciona herramientas para obtener y configurar el modo de red en tiempo de ejecución:

obtener_modo_de_red

Obtenga la configuración del modo de red actual.

{
  "name": "get_network_mode",
  "arguments": {}
}

establecer_modo_de_red

Establecer el modo de red activo.

{
  "name": "set_network_mode",
  "arguments": {
    "mode": "testnet_only"
  }
}

Herramientas de blockchain

Todas las herramientas admiten un parámetro network opcional para especificar qué red utilizar ('mainnet' o 'testnet').

obtener_información_de_la_cadena_de_bloques

Obtenga información general sobre la cadena de bloques Neo N3.

{
  "name": "get_blockchain_info",
  "arguments": {
    "network": "testnet"
  }
}

obtener_bloque

Obtenga detalles del bloque por altura o hash.

{
  "name": "get_block",
  "arguments": {
    "hashOrHeight": 12345,
    "network": "mainnet"
  }
}

obtener_transacción

Obtenga detalles de la transacción por hash.

{
  "name": "get_transaction",
  "arguments": {
    "txid": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "network": "testnet"
  }
}

obtener_saldo

Obtener el saldo de la cuenta para una dirección específica.

{
  "name": "get_balance",
  "arguments": {
    "address": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ",
    "network": "mainnet"
  }
}

transferencia_de_activos

Transferir activos entre direcciones.

{
  "name": "transfer_assets",
  "arguments": {
    "fromWIF": "KwDZGCUXYAB1cUNmZKQ5RFUBAYPjwXvpavQQHvpeH1qM5pJ3zurn",
    "toAddress": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ",
    "asset": "NEO",
    "amount": "1",
    "confirm": true,
    "network": "testnet"
  }
}

invocar_contrato

Invocar un método de contrato inteligente.

{
  "name": "invoke_contract",
  "arguments": {
    "fromWIF": "KwDZGCUXYAB1cUNmZKQ5RFUBAYPjwXvpavQQHvpeH1qM5pJ3zurn",
    "scriptHash": "0x8c23f196d8a1bfd103a9dcb1f9ccf0c611377d3b",
    "operation": "transfer",
    "args": [
      {
        "type": "Hash160",
        "value": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ"
      },
      {
        "type": "Hash160",
        "value": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ"
      },
      {
        "type": "Integer",
        "value": "1"
      },
      {
        "type": "Any",
        "value": null
      }
    ],
    "confirm": true,
    "network": "testnet"
  }
}

crear_billetera

Crea una nueva billetera.

{
  "name": "create_wallet",
  "arguments": {
    "password": "your-secure-password",
    "network": "mainnet"
  }
}

importar_billetera

Importar una billetera existente desde WIF o una clave encriptada.

{
  "name": "import_wallet",
  "arguments": {
    "key": "KwDZGCUXYAB1cUNmZKQ5RFUBAYPjwXvpavQQHvpeH1qM5pJ3zurn",
    "password": "your-secure-password",
    "network": "testnet"
  }
}

Recursos

Estado de la red Neo N3

Red predeterminada (según la configuración):

neo://network/status

Redes específicas:

neo://mainnet/status
neo://testnet/status

Bloque Neo N3 por altura

Red predeterminada:

neo://block/{height}

Redes específicas:

neo://mainnet/block/{height}
neo://testnet/block/{height}

Saldo de direcciones de Neo N3

Red predeterminada:

neo://address/{address}/balance

Redes específicas:

neo://mainnet/address/{address}/balance
neo://testnet/address/{address}/balance

Pruebas

El servidor Neo N3 MCP incluye pruebas exhaustivas para garantizar su funcionalidad. Hay varias maneras de ejecutar las pruebas:

Uso de Jest (pruebas de TypeScript)

Las pruebas Jest proporcionan una prueba integral con una simulación adecuada:

# Install dependencies first
npm install

# Run all Jest tests
npm test

# Run specific test files
npx jest tests/utils/validation.test.ts
npx jest tests/contracts/contract-service.test.ts

El conjunto de pruebas incluye pruebas para:

Servicios principales:
- Servicio Neo (interacciones blockchain)
- Servicio de contrato (interacciones de contrato inteligente)
Utilidades:
- Validación (validación de parámetros de entrada)
- Manejo de errores (respuestas de error estandarizadas)
- Caché (almacenamiento en caché en memoria con TTL)
- Limitación de velocidad (limitación de solicitudes)
Componentes del sitio web:
- Funcionalidad de la página principal
- Navegación por la página de documentación
- Interacciones del patio de juegos de API
- Funcionalidad del explorador de bloques
- Interfaz de chat

Uso de Simple Test Runner (JavaScript)

También están disponibles ejecutores de pruebas de JavaScript simplificados para realizar pruebas rápidas:

# Run the simplified test
node tests/simple-test.js

# Run network test
node tests/network-test.js

# Run transaction status test
node tests/transaction-status-test.js

Estas pruebas cubren la funcionalidad principal de la API sin requerir la compilación de TypeScript.

Desarrollo y contribución

Publicación

Para publicar el paquete en los registros NPM y/o Docker:

# Publish to NPM
npm run publish:npm

# Build and publish Docker image
npm run publish:docker

# Publish to both
npm run publish:all

Configuración de desarrollo

Para el desarrollo, utilice:

# Build with TypeScript watching
npm run dev

Consideraciones de seguridad

Las claves privadas nunca se exponen en las respuestas
Las operaciones sensibles (transferencias, invocaciones de contratos) requieren confirmación explícita
La validación de entrada se realiza para todos los parámetros
Los mensajes de error están diseñados para ser informativos sin exponer información confidencial.

Detalles técnicos

Arquitectura de servicios

El servidor Neo N3 MCP está estructurado en torno a varios componentes clave:

Interfaz MCP : implementada en src/index.ts - Maneja la comunicación del protocolo MCP
Servicio Neo : Implementado en src/services/neo-service.ts - Interacciones de la cadena de bloques Core Neo N3
Validación : Implementado en src/utils/validation.ts - Validación de parámetros
Manejo de errores : implementado en src/utils/error-handler.ts - Respuestas de error estandarizadas

Manejo de errores

Los errores se estandarizan a través de la función handleError que:

Convierte errores específicos de Neo N3 en mensajes fáciles de usar
Enmascara información sensible
Proporciona información clara y práctica a los usuarios.

Redes

El servidor gestiona automáticamente los reintentos y errores de red al conectarse a la red blockchain Neo N3. Los parámetros de conexión, como los tiempos de espera y los reintentos, se pueden configurar mediante variables de entorno.

Estructura del proyecto

El proyecto está organizado de la siguiente manera:

neo-n3-mcp/
├── src/
│   ├── services/
│   │   └── neo-service.ts       # Core Neo N3 blockchain interaction
│   ├── utils/
│   │   ├── validation.ts        # Input validation
│   │   └── error-handler.ts     # Error handling and responses
│   ├── config.ts                # Configuration settings
│   └── index.ts                 # MCP server and tool definitions
├── tests/
│   ├── neo-service.test.ts      # Jest tests for NeoService
│   └── simple-test.js           # Simple JavaScript test runner
├── scripts/
│   ├── add-to-mcp-settings.js   # Script to add to MCP settings
│   ├── publish-npm.js           # Script to publish to NPM
│   └── publish-docker.sh        # Script to build and publish Docker image
├── wallets/                     # Wallet storage directory
├── dist/                        # Compiled TypeScript output
├── docker-compose.yml           # Docker Compose configuration
├── Dockerfile                   # Docker container definition
├── package.json                 # Node.js package definition
└── tsconfig.json                # TypeScript configuration

Expresiones de gratitud

Este proyecto no sería posible sin lo siguiente:

@cityofzion/neon-js - El SDK oficial de JavaScript para la blockchain Neo N3, que proporciona la funcionalidad principal para interactuar con la red Neo N3. Agradecemos especialmente al equipo de la Ciudad de Zion por su continuo desarrollo y mantenimiento de esta biblioteca esencial.
Protocolo MCP : para proporcionar el protocolo estandarizado para que los sistemas de IA interactúen con herramientas y recursos externos.

Licencia

Este servidor MCP está licenciado bajo la licencia MIT. Consulte el archivo de licencia para obtener más información.

Famosos contratos de Neo N3

El servidor MCP de Neo N3 ahora incluye soporte para interactuar con contratos famosos de Neo N3 como:

NeoFS : Sistema de almacenamiento descentralizado en la blockchain Neo N3
NeoBurger : Servicio de staking de Neo N3
Flamingo (FLM) : Plataforma DeFi Neo N3
NeoCompound : Protocolo de cultivo automático de rendimiento en Neo N3
GrandShare : Protocolo de reparto de beneficios en Neo N3
GhostMarket : Mercado NFT en Neo N3

Herramientas de contrato

Listado e información

list_famous_contracts : Lista todos los contratos famosos de Neo N3 compatibles
get_contract_info : Obtener detalles sobre un contrato famoso específico

Herramientas NeoFS

neofs_create_container : Crea un contenedor de almacenamiento en NeoFS
neofs_get_containers : Obtener contenedores propiedad de una dirección

Herramientas de NeoBurger

neoburger_deposit : Deposita NEO en NeoBurger para recibir tokens bNEO
neoburger_withdraw : Retira NEO de NeoBurger devolviendo tokens bNEO
neoburger_get_balance : Obtener el saldo bNEO de una cuenta
neoburger_claim_gas : Reclama las recompensas de GAS acumuladas de NeoBurger

Herramientas Flamingo

flamingo_stake : Apuesta tokens FLM en Flamingo
flamingo_unstake : Retirar tokens FLM de Flamingo
flamingo_get_balance : Obtener el saldo del token FLM

Herramientas NeoCompound

neocompound_deposit : Deposita activos en NeoCompound
neocompound_withdraw : Retira activos de NeoCompound
neocompound_get_balance : Obtener el saldo de los activos depositados en NeoCompound

grandshare_deposit : Deposita activos en el fondo GrandShare
grandshare_withdraw : Retirar activos del fondo GrandShare
grandshare_get_pool_details : Obtener detalles sobre un grupo de GrandShare

Herramientas de GhostMarket

ghostmarket_create_nft : Crea un nuevo NFT en GhostMarket
ghostmarket_list_nft : Publica un NFT para la venta en GhostMarket
ghostmarket_buy_nft : Compra un NFT listado en GhostMarket
ghostmarket_get_token_info : Obtén información sobre un NFT en GhostMarket

Ejemplos

Obtener una lista de contratos famosos

const result = await callTool('list_famous_contracts', {
  network: 'mainnet'
});

Obtener información del contrato

const result = await callTool('get_contract_info', {
  contractName: 'flamingo',
  network: 'mainnet'
});

Depositar en NeoBurger

const result = await callTool('neoburger_deposit', {
  fromWIF: 'your-private-key-wif-format',
  confirm: true,
  network: 'mainnet'
});

Apostando por Flamingo

const result = await callTool('flamingo_stake', {
  fromWIF: 'your-private-key-wif-format',
  amount: '100',
  confirm: true,
  network: 'mainnet'
});

Depositar en NeoCompound

const result = await callTool('neocompound_deposit', {
  walletPath: '/path/to/wallet.json',
  walletPassword: 'your-password',
  assetId: '0xd2a4cff31913016155e38e474a2c06d08be276cf',
  amount: '100',
  network: 'mainnet'
});

Creando un NFT en GhostMarket

const result = await callTool('ghostmarket_create_nft', {
  walletPath: '/path/to/wallet.json',
  walletPassword: 'your-password',
  tokenURI: 'https://example.com/nft/metadata.json',
  properties: [
    { key: "artist", value: "ExampleArtist" },
    { key: "edition", value: "1/1" }
  ],
  network: 'mainnet'
});

const result = await callTool('grandshare_get_pool_details', {
  poolId: 1,
  network: 'mainnet'
});

Integrations