Servidor MCP de Starknet

Un servidor integral de Protocolo de Contexto de Modelo (MCP) para la blockchain de Starknet. Este servidor proporciona a los agentes de IA la capacidad de interactuar con las redes de Starknet, consultar datos de la blockchain, gestionar billeteras e interactuar con contratos inteligentes.

📋 Contenido

• Descripción general
• Características
• Redes compatibles
• Prerrequisitos
• Instalación
• Configuración del servidor
• Uso
• Referencia de API
  • Herramientas
  • Recursos
  • Indicaciones
• Uso con asistentes de IA
• Consideraciones de seguridad
• Estructura del proyecto
• Convenciones de desarrollo
• Documentación
• Licencia

🔭 Descripción general

El servidor MCP de Starknet aprovecha el Protocolo de Contexto de Modelo para proporcionar servicios de blockchain a agentes de IA. Ofrece una interfaz integral con el ecosistema de Starknet, lo que permite a los asistentes de IA interactuar con los datos y operaciones de la blockchain de Starknet mediante lenguaje natural.

Las capacidades clave incluyen:

• Lectura del estado de la blockchain (saldos, transacciones, bloques)
• Interacción con los contratos inteligentes de El Cairo
• Transferencia de tokens (ETH, STRK y otros tokens ERC20)
• Trabajar con NFT y metadatos de tokens
• Resolución de dominios StarknetID (similar a ENS para Ethereum)
• Realizar operaciones de lectura y escritura con un manejo adecuado de las transacciones

Todos los servicios se exponen mediante una interfaz consistente de herramientas y recursos MCP, lo que facilita a los agentes de IA descubrir y utilizar la funcionalidad de la blockchain de Starknet. Todas las herramientas que aceptan direcciones de Starknet también son compatibles con StarknetID , lo que resuelve automáticamente las identidades legibles por humanos en direcciones en segundo plano.

✨ Características

• Integración con Starknet : Integración completa de la cadena de bloques de Starknet mediante Starknet.js
• Soporte de red : compatible con Mainnet y Testnet Sepolia
• Integración de StarknetID : Resolución de identificaciones de Starknet a direcciones y viceversa
• Compatibilidad con tokens nativos : compatibilidad con tokens nativos ETH y STRK
• Interacción de contratos inteligentes : llamar y consultar contratos inteligentes de Starknet
• Transporte dual : Ejecútelo como servidor stdio o servidor HTTP para diferentes necesidades de integración
• Listo para IA : diseñado para usarse con Claude, GPT y otros asistentes de IA

Información de blockchain

• Consultar información de la cadena (ID de la cadena, último bloque)
• Explorar detalles de bloques y transacciones
• Ver recibos y estados de transacciones
• Obtener información de dirección y datos del contrato

Operaciones de tokens nativos

• Obtenga saldos de ETH y STRK para cualquier dirección
• Transferir ETH y STRK entre cuentas
• Ver saldos combinados de tokens nativos

Operaciones de tokens

• Obtenga saldos e información de tokens ERC20
• Transferir tokens ERC20
• Ver el suministro de tokens y los metadatos
• Verificar la propiedad del token

Operaciones NFT

• Verificar la propiedad de NFT por ID de token
• Obtenga información sobre la colección de NFT
• Ver saldos de NFT por dirección

Interacción de contratos inteligentes

• Llamar a funciones de contrato de solo lectura
• Ejecutar escrituras de contrato con confirmación de transacción
• Obtenga información sobre el almacenamiento por contrato
• Ver información de ABI y clase de contrato

Identificación de Starknet

• Resolver direcciones de Starknet a ID de Starknet
• Resolver las identificaciones de Starknet en direcciones
• Obtenga perfiles completos de Starknet ID con datos de verificación
• Validar dominios de Starknet

🔧 Redes compatibles

El servidor admite las siguientes redes Starknet:

• Mainnet : La red de producción principal de Starknet
• Sepolia : la red de prueba de Starknet en Sepolia de Ethereum

🛠️ Requisitos previos

• Bun 1.0.0 o superior (recomendado)
• Node.js 18.0.0 o superior

📦 Instalación

Opción 1: Usar sin instalación (npx)

La forma más fácil de comenzar es usar npx para ejecutar el paquete directamente:

Esto descargará y ejecutará automáticamente la última versión sin necesidad de instalarla primero.

Opción 2: Instalación global

Si planeas usarlo con frecuencia, puedes instalarlo globalmente:

Opción 3: Instalación del proyecto local

Luego agrega a tus scripts package.json:

Opción 4: Ejecutar desde la fuente

Si desea ejecutar desde la fuente o desarrollar localmente:

Para desarrollo con recarga automática:

⚙️ Configuración del servidor

El servidor utiliza la siguiente configuración predeterminada:

• Red predeterminada : Red principal
• Puerto del servidor : 3000 (modo HTTP)
• Host del servidor : 0.0.0.0 (accesible desde cualquier interfaz de red)

Estos valores están codificados en la aplicación. Si necesita modificarlos, puede editar los siguientes archivos:

• Para la configuración de la red: src/core/chains.ts
• Para la configuración del servidor: src/server/http-server.ts

🔍 Uso

Ejecución del servidor

Puede ejecutar el servidor MCP de Starknet en dos modos:

El servidor HTTP se ejecuta en el puerto 3000 de forma predeterminada y proporciona una API REST y eventos enviados por el servidor (SSE) para la comunicación en tiempo real.

Conectando desde el cursor

Para conectarse al servidor MCP de Starknet desde Cursor:

1. Abra Cursor y vaya a Configuración (ícono de engranaje en la parte inferior izquierda)
2. Haga clic en "Funciones" en la barra lateral izquierda.
3. Desplácese hacia abajo hasta la sección "Servidores MCP".
4. Haga clic en "Agregar nuevo servidor MCP"
5. Introduzca los siguientes datos:
   • Nombre del servidor: starknet-mcp-server
   • Tipo: command
   • Comando: npx @mcpdotdirect/starknet-mcp-server
6. Haga clic en "Guardar"

Una vez conectado, podrá usar las funciones del servidor MCP directamente desde Cursor. El servidor aparecerá en la lista de servidores MCP y podrá habilitarlo o deshabilitarlo según sea necesario.

Usando mcp.json con Cursor

Para una configuración más portátil que pueda compartir con su equipo o usar en diferentes proyectos, puede crear un archivo .cursor/mcp.json en el directorio raíz de su proyecto:

Coloque este archivo en el directorio .cursor de su proyecto (créelo si no existe) y Cursor detectará y utilizará automáticamente estas configuraciones de servidor MCP cuando trabaje en ese proyecto.

Modo HTTP con SSE

Si está desarrollando una aplicación web y desea conectarse al servidor HTTP con eventos enviados por el servidor (SSE), puede usar esta configuración:

Conexión mediante Claude CLI

Si está utilizando Claude CLI, puede conectarse al servidor MCP con solo dos comandos:

Ejemplo: Uso del servidor MCP en Cursor

Después de configurar el servidor MCP, puede usarlo fácilmente en Cursor. Por ejemplo:

1. Crea un nuevo archivo JavaScript/TypeScript en tu proyecto:

2. Con el archivo abierto en Cursor, puedes pedirle a Cursor que:
   • Consulta el saldo de ETH de vitalik.stark.
   • Obtén información sobre el último bloque en Starknet.
   • "Buscar el propietario del NFT #123 en la colección 0x..."

Ejemplo: Obtener un saldo de ETH con Starknet ID

Ejemplo: Resolución de una ID de Starknet

Ejemplo: Llamar a un contrato inteligente

Uso en un proyecto Node.js

Si desea utilizar programáticamente el servidor MCP en su proyecto Node.js:

Para un uso más avanzado, puede crear una clase contenedora alrededor de la API HTTP o utilizar bibliotecas como Axios para llamadas de API más limpias.

Referencia de API

Herramientas MCP disponibles

Este servidor implementa las siguientes herramientas MCP:

Herramientas de red

• get_starknet_chain_info : Obtener información sobre una red Starknet
• get_supported_starknet_networks : Obtenga una lista de redes Starknet compatibles

Herramientas de equilibrio

• get_starknet_eth_balance : obtiene el saldo de ETH para una dirección o ID de Starknet
• get_starknet_token_balance : obtiene el saldo de cualquier token para una dirección
• get_starknet_strk_balance : obtiene el saldo del token STRK para una dirección
• get_starknet_native_balances : obtiene todos los saldos de tokens nativos (ETH y STRK) para una dirección

Herramientas de StarknetID

• resolve_starknet_name : Obtener el ID de Starknet para una dirección
• resolve_starknet_address : Obtener la dirección de una ID de Starknet
• get_starknet_profile : obtiene el perfil de identificación de Starknet completo para una dirección
• validate_starknet_domain : Comprueba si una cadena es un ID de Starknet válido

Herramientas de bloque

• get_starknet_block : Obtener información sobre un bloque específico
• get_starknet_block_transactions : Obtener transacciones en un bloque específico

Herramientas de transacción

• get_starknet_transaction : Obtener detalles sobre una transacción
• get_starknet_transaction_receipt : Obtener el recibo de la transacción
• check_starknet_transaction_status : Comprueba si una transacción está confirmada

Herramientas de contrato

• call_starknet_contract : Llamar a una función de solo lectura en un contrato
• get_starknet_contract_class : Obtener la clase (ABI y otra información) de un contrato
• execute_starknet_contract : Ejecutar una llamada de contrato (operación de escritura)

Herramientas de token

• get_starknet_token_info : Obtener información sobre un token
• get_starknet_token_supply : Obtener el suministro total de un token
• check_starknet_nft_ownership : Comprueba si una dirección posee un NFT específico
• get_starknet_nft_balance : obtiene la cantidad de NFT que posee una dirección

Herramientas de transferencia

• transfer_starknet_eth : transfiere ETH de una cuenta a otra (cantidades en formato legible para humanos)
• transfer_starknet_strk : Transferir STRK de una cuenta a otra (cantidades en formato legible para humanos)
• transfer_starknet_token : transfiere tokens ERC20 de una cuenta a otra (cantidades en formato legible para humanos)

Recursos MCP disponibles

El servidor proporciona los siguientes recursos MCP:

Recursos de red

• starknet://{network}/chain : Obtener información de la cadena para una red específica
• starknet://networks : Obtenga una lista de todas las redes compatibles

Recursos del bloque

• starknet://{network}/block/{blockIdentifier} : Obtener información sobre un bloque específico
• starknet://{network}/block/latest : Obtener el último bloque

Recursos de dirección

• starknet://{network}/address/{address} : Obtener información sobre una dirección

Recursos de transacción

• starknet://{network}/tx/{txHash} : Obtener información de la transacción

Recursos de StarknetID

• starknet://{network}/id/address/{address} : Resolver una dirección a un ID de Starknet
• starknet://{network}/id/name/{name} : Resolver un ID de Starknet a una dirección
• starknet://{network}/id/profile/{address} : Obtener el perfil de identificación de Starknet para una dirección

Indicaciones de MCP disponibles

Para las interacciones LLM, el servidor proporciona estas indicaciones:

• explore_starknet_block : Explora información sobre un bloque específico de Starknet
• explore_starknet_address : Obtener información sobre una dirección de Starknet
• explore_starknet_transaction : Obtener información sobre una transacción de Starknet
• lookup_starknet_id : busca un ID de Starknet o resuelve una dirección a un ID de Starknet
• explore_starknet_id_profile : Explora un perfil completo de Starknet ID

🔍 Uso con asistentes de IA

Al utilizar este servidor con asistentes de IA como Claude o GPT:

1. Configura tu asistente de IA para usar este servidor MCP
2. El asistente puede luego usar herramientas para interactuar con Starknet.
3. Consultas de ejemplo:
   • "¿Cuál es el saldo de ETH de la dirección 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d?"
   • "Buscar el ID de Starknet para la dirección 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d"
   • "¿Qué hay en el último bloque en la red principal de Starknet?"
   • Obtener información sobre la transacción 0x7e3a33ab42f2e24184763563b7b8482b53e3b89831ebc3eacf29d4d11f5198
   • "Resolver el ID de Starknet vitalik.stark a una dirección"

Consideraciones de seguridad

• Las claves privadas se utilizan únicamente para firmar transacciones y nunca las almacena el servidor.
• Todas las cantidades de tokens se especifican en formato legible para humanos (por ejemplo, ETH, STRK, unidades de token) en lugar de en wei o unidades más pequeñas.
• Siempre valide y desinfecte los parámetros de entrada antes de ejecutar operaciones
• Considere implementar mecanismos de autenticación adicionales para el uso en producción
• Utilice HTTPS para el servidor HTTP en entornos de producción
• Implementar la limitación de velocidad para evitar el abuso
• Para servicios de alto valor, considere agregar pasos de confirmación

📁 Estructura del proyecto

🛠️ Convenciones de Desarrollo

Al agregar herramientas, recursos o indicaciones personalizadas:

1. Utilice guiones bajos ( _ ) en lugar de guiones ( - ) en todos los nombres de recursos, herramientas y avisos.
   // Good: Uses underscores server.tool( "starknet_contract_call", "Description of the tool", { contract_address: z.string().describe("The contract address") }, async (params) => { // Tool implementation } );
2. Esta convención de nomenclatura garantiza la compatibilidad con Cursor y otras herramientas de IA.

📚 Documentación

Para obtener más información sobre:

• Protocolo de contexto modelo
• Documentación de Starknet.js
• Documentación de Starknet
• Documentación de StarknetID

📄 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.