Servidor de inscripción MCP

Descripción general

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite que los modelos de IA interactúen con inscripciones ordinales, lo que les permite mostrar contenido de una transacción.

Related MCP server: MCP Bitcoin CLI

🎮 Demostración

💼 Índice de contenidos

• Servidor de inscripción MCP

  • Descripción general

  • 💼 Índice de contenidos

  • 🔧 Características

  • 🦆 Integración de Goose

    • Uso de STDIO (extensión local)

      • Uso de SSE (extensión remota)

  • 🔑 Integración de escritorio de Claude

    • Prueba de la integración de Claude Desktop

  • 📂 Estructura del proyecto

  • Configuración del desarrollo

  • 📦 Herramientas disponibles

    • mostrar_ordinales

  • 🚨 Manejo de errores

  • 🤝 Contribuyendo

  • 📝 Licencia

🔧 Características

• Detección de ordinales : detecta y analiza automáticamente las transacciones de Bitcoin en ordinales, admitiendo formatos de inscripciones basados en texto, imágenes, JSON y más.

🦆 Integración de Goose

Goose es un framework de agente de IA de código abierto de Block que admite extensiones mediante el Protocolo de Contexto de Modelo. Puede integrar el servidor MCP-Inscription como una extensión de Goose para que Goose interactúe con las inscripciones ordinales. Goose admite dos modos de integración para servidores MCP: ejecutar el servidor como un proceso local (STDIO) o conectarse a él como un servicio remoto mediante Eventos Enviados por el Servidor (SSE). A continuación, se detallan las instrucciones para ambos métodos:

Uso de STDIO (extensión local)

Este método ejecuta el servidor MCP-Inscription localmente como un subproceso de Goose, comunicándose a través de entrada/salida estándar.

1. Clonar y crear el repositorio de inscripciones MCP (si aún no lo ha hecho):

   git clone https://github.com/Laz1mov/mcp-inscription
   cd mcp-inscription
   npm install
   npm run build

   Anote la ruta absoluta completa al repositorio, ya que la necesitará en el siguiente paso.

2. Añadir una nueva extensión en Goose: Abra la interfaz de configuración de Goose. Puede hacerlo mediante la línea de comandos ejecutando goose configure o en la aplicación Goose Desktop, en Configuración > Extensiones . En el menú, seleccione "Añadir extensión". ( Usar extensiones | goose )

3. Elija el tipo de extensión: Extensión de línea de comandos: cuando se le solicite el tipo de extensión, seleccione Extensión de línea de comandos (en el menú CLI o UI) para que Goose sepa que debe iniciar un comando local ( Uso de extensiones | goose ) (en lugar de una extensión integrada o remota).

4. Ingrese los detalles de la extensión: Proporcione un nombre y un comando para el servidor MCP-Inscription:

   • ID : mcp-inscription

   • Nombre: Puedes llamarlo “mcp-inscription” o cualquier identificador (así será como te referirás a la extensión).

   • Comando: Especifique la ruta completa del script CLI generado. Por ejemplo:

     node /absolute/path/to/mcp-inscription/build/cli.js

     Reemplace /absolute/path/to/mcp-inscription con la ruta real a donde clonó el repositorio.

   • Generalmente no es necesario agregar ningún argumento más allá de la ruta del script (a menos que su servidor requiera indicadores especiales).

5. Finalizar y habilitar: Complete la adición de la extensión. Goose añadirá esta nueva extensión a su configuración (normalmente ~/.config/goose/config.yaml ). Asegúrese de que la extensión esté habilitada (si usa el asistente de la CLI, debería estar habilitada por defecto una vez añadida; en la aplicación Goose Desktop, puede consultar la lista de extensiones y activarla si no lo está ya ( Usar extensiones | goose ) ( Usar extensiones | goose )).

6. Iniciar una sesión de Goose con la nueva extensión: Ahora puede usar la extensión en Goose. Si ejecuta Goose mediante la CLI, inicie una sesión que incluya la extensión ejecutando:

   goose session --with-extension "mcp-inscription"

Reemplazar "ordinales" por el nombre asignado a la extensión ( Uso de extensiones | goose ). (Esto garantiza que la sesión cargue la extensión. Alternativamente, si la extensión está habilitada globalmente, Goose Desktop o CLI la tendrán disponible automáticamente en todas las sesiones).

Uso de SSE (extensión remota)

Este método conecta Goose a un servidor MCP en ejecución mediante una secuencia HTTP SSE. Úselo si desea ejecutar el servidor MCP-Inscription como un servicio independiente (posiblemente en otra máquina o de forma independiente de Goose).

1. Inicie el servidor MCP como un servicio independiente: ejecute el servidor MCP-Inscription en modo SSE para escuchar conexiones:

   # Navigate to your mcp-inscription directory
   cd /path/to/mcp-inscription
   
   # If you havent built it yet
   npm install
   npm run build
   
   # Run in SSE mode on port 3000 (default)
   SERVER_MODE=sse node build/cli.js
   
   # Alternatively, specify a different port
   SERVER_MODE=sse PORT=9000 node build/cli.js

   Esto iniciará el servidor en modo SSE, haciéndolo disponible en http://localhost:3000 (o el puerto especificado).

2. Añadir una nueva extensión en Goose (Remoto): Como antes, ejecute goose configure o use la interfaz de usuario de Goose para añadir una extensión ( Uso de extensiones | goose ). Esta vez, seleccione Extensión remota cuando se le solicite el tipo de extensión ( Uso de extensiones | goose ). Esto indica a Goose que se conectará a un servidor externo mediante SSE.

3. Ingrese los detalles de la extensión remota: Asigne un nombre a la extensión (p. ej., "ordinales") y proporcione la URL del servidor. Para la URL , ingrese la dirección base donde se ejecuta el servidor MCP. Por ejemplo, si su servidor escucha en el puerto 9000 de su equipo local, podría ingresar http://localhost:9000 . Goose intentará conectarse al punto final SSE del servidor MCP en esa dirección. (Goose usa la ruta SSE estándar de MCP, que por convención se encuentra bajo la ruta /mcp/sse del servidor; normalmente, solo necesita proporcionar el host y el puerto, y Goose se encarga del resto).

4. Habilitar la extensión: Después de agregar la extensión remota, asegúrese de que esté habilitada en la configuración de Goose (igual que en el caso de STDIO). Solo es necesario habilitar una de las extensiones, STDIO o SSE (con las mismas herramientas). Si habilita accidentalmente una versión local y otra remota del mismo servidor, le recomendamos deshabilitar una para evitar confusiones.

Uso de la extensión MCP-Inscription en Goose: Una vez configurada y habilitada la extensión (mediante cualquiera de los métodos anteriores), podrá interactuar con Goose y consultar datos de pedidos a través de ella. En un nuevo chat o sesión de Goose, simplemente haga preguntas como lo haría normalmente. Goose reconocerá cuándo usar las herramientas de MCP-Inscription para atender su solicitud. Por ejemplo:

• "Muéstrame los ordinales: 0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389?"

Al hacer estas preguntas, Goose invocará las herramientas del servidor MCP-Inscription y devolverá la respuesta (por ejemplo, la información más reciente del bloque de Bitcoin). Debería ver a Goose respondiendo con información actualizada extraída de la blockchain de Bitcoin a través del servidor MCP-Inscription.

Si Goose no parece usar la extensión (por ejemplo, si indica que no encuentra la información), asegúrese de que esté habilitada y de que el servidor esté ejecutándose (en modo SSE para acceso remoto). También puede ejecutar la CLI de Goose con registro detallado para comprobar si intentó llamar a la extensión. Generalmente, si se configura correctamente, Goose detectará automáticamente las capacidades del servidor MCP-Inscription y las usará cuando sea necesario.

Recursos adicionales: Para más detalles sobre las extensiones de Goose y el MCP, consulte la documentación oficial de Goose ( Uso de extensiones | goose ). La documentación incluye una lista de extensiones integradas y de la comunidad, y explica cómo se integran los servidores MCP en Goose. También puede encontrar un directorio de servidores MCP disponibles y consejos de configuración adicionales en la documentación de Goose y la documentación del Protocolo de Contexto de Modelo. Esto puede ser útil si desea explorar más extensiones o desarrollar las suyas propias.

🔑 Integración de escritorio de Claude

Para utilizar el servidor MCP-Inscription con Claude Desktop (la aplicación de escritorio de Anthropic para Claude), siga estos pasos:

1. Descarga e instala Claude Desktop: Visita la página oficial de descargas de Claude Desktop y descarga la app para tu sistema operativo (MacOS o Windows) ( Instalación de Claude Desktop | Centro de ayuda de Anthropic ). Instala la app y asegúrate de usar la última versión (puedes buscar actualizaciones en el menú de la app).

2. Clonar y crear el repositorio de inscripciones MCP:

   git clone https://github.com/Laz1mov/mcp-inscription
   cd mcp-inscription
   npm install
   npm run build

3. Configure Claude Desktop para usar el servidor MCP-Inscription: abra el archivo de configuración de Claude Desktop (se crea cuando edita por primera vez la configuración en Claude Desktop):

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Ventanas: %APPDATA%\Claude\claude_desktop_config.json
     Agregue una entrada para el servidor MCP-Inscription en esta configuración JSON, en la sección "mcpServers" . Por ejemplo:

   {
     "mcpServers": {
       "mcp-inscription": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-inscription/build/cli.js"]
       }
     }
   }

   En el fragmento anterior, "mcp-inscription" es un identificador del servidor (puedes ponerle el nombre que quieras). Reemplaza /absolute/path/to/mcp-inscription por la ruta completa donde clonaste el repositorio.

4. Reinicie Claude Desktop: Guarde el archivo claude_desktop_config.json y cierre y vuelva a abrir Claude Desktop . La próxima vez que inicie, Claude iniciará automáticamente el servidor MCP-Inscription según su configuración. Si Claude Desktop estaba en ejecución, deberá reiniciarlo para que los cambios surtan efecto.

Prueba de la integración de Claude Desktop

Una vez reiniciado Claude Desktop, puedes probar si el servidor MCP-Inscription funciona correctamente:

• Verificar la respuesta: Claude debería devolver una respuesta detallada (por ejemplo, la inscripción o información sobre las runas) sin errores. Si recibe un mensaje de error o ninguna respuesta útil, es posible que el servidor MCP no esté conectado correctamente.

• Revisar los registros de Claude (si es necesario): Claude Desktop proporciona archivos de registro que pueden ayudar a depurar las integraciones de MCP. Si la herramienta no responde, revise los archivos de registro en:

  • macOS: ~/Library/Logs/Claude/

  • Ventanas: %APPDATA%\Claude\logs\
    Busque el mcp.log para los mensajes generales de conexión de MCP y un archivo llamado mcp-server-mcp-inscription.log (o con el nombre que haya usado) para la salida/errores del servidor MCP. Estos registros mostrarán si el servidor se inició o si hubo algún error (como una ruta incorrecta o excepciones en el servidor). Si detecta errores, corrija la configuración o el entorno según sea necesario, reinicie Claude Desktop y vuelva a probar.

📂 Estructura del proyecto

mcp-inscription/
├── src/
│   ├── ordinals_client.ts      # Bitcoin ordinals and runestone utility functions
│   ├── servers/
│   │   ├── index.ts            # Server exports and factory functions
│   │   ├── sse.ts              # Server implementation using SSE transport
│   │   ├── stdio.ts            # Server implementation using STDIO transport
│   │   └── base.ts             # Base server implementation with shared functionality
│   ├── index.ts                # Main entry point
│   ├── cli.ts                  # CLI launcher
│   ├── mcp_inscription_types.ts # Shared types and schemas for the MCP-Inscription server
│   └── utils/
│       ├── logger.ts           # Logger setup
│       ├── cache.ts            # Caching implementation
│       ├── error_handlers.ts   # Error handling utilities
│       ├── json_utils.ts       # JSON processing utilities
│       ├── img_utils.ts        # Image processing and conversion utilities
│       └── version.ts          # Version information
├── .env.example                # Example environment configuration file
├── package.json
├── tsconfig.json
└── README.md

📦 Herramientas disponibles

mostrar_ordinales

Descripción:
Decodifica datos de inscripción ordinal a partir de los datos de testigos de una transacción.

Esquema de entrada:

{
  "txid": "string"
}

Ejemplo de entrada:

{
  "txid": "0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389"
}

Producción:
Devuelve el contenido de la inscripción decodificada, que puede ser texto, JSON, HTML u otros formatos.

🚨 Manejo de errores

El servidor utiliza tipos de error personalizados para gestionar las operaciones de Bitcoin y las consultas de blockchain. Los mensajes de error detallados se registran mediante Pino y se incluyen en las respuestas del cliente para facilitar la depuración.

🤝 Contribuyendo

¡Agradecemos sus contribuciones y solicitudes de funcionalidad! No dude en enviar solicitudes de incorporación de cambios o abrir incidencias en GitHub.

📝 Licencia

Este proyecto está licenciado bajo la licencia MIT .