Servidor MCP de Stampchain

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con datos de Bitcoin Stamps y tokens SRC-20 a través de la API de Stampchain. Este servidor proporciona a los clientes compatibles con MCP herramientas para consultar Bitcoin Stamps, colecciones y tokens SRC-20.

Características

Herramientas de Bitcoin Stamps: Obtén detalles de stamps, busca stamps y recupera stamps recientes
Colecciones de Stamps: Consulta colecciones y busca en los datos de colecciones
Tokens SRC-20: Obtén información de tokens y busca entre tokens SRC-20
Seguro en tipos: Construido con TypeScript y validación Zod
Pruebas exhaustivas: Cobertura completa de pruebas con validación CI
Configurable: Opciones de configuración flexibles para diferentes entornos
Multiplataforma: Funciona en Ubuntu, Windows y macOS con Node.js 18+

Inicio rápido

Requisitos previos

Node.js 18+
npm o yarn

Instalación

Clona el repositorio:

git clone https://github.com/stampchain-io/stampchain-mcp.git
cd stampchain-mcp

Instala las dependencias:
```
npm install
```
Compila el proyecto:
```
npm run build
```
Prueba la instalación:
```
npm run start
```

Integración con clientes MCP

Claude Desktop

Para usar con Claude Desktop, añade lo siguiente a tu claude_desktop_config.json:

{
  "mcpServers": {
    "stampchain": {
      "command": "node",
      "args": ["/path/to/stampchain-mcp/dist/index.js"],
      "cwd": "/path/to/stampchain-mcp"
    }
  }
}

Alternativa: Usando npx (recomendado)

Para una configuración más sencilla sin instalación local:

{
  "mcpServers": {
    "stampchain": {
      "command": "npx",
      "args": ["-y", "stampchain-mcp"]
    }
  }
}

Nota: Reemplaza /path/to/stampchain-mcp con la ruta real a tu directorio de instalación.

Otros clientes MCP

Este servidor implementa el protocolo MCP estándar y puede usarse con cualquier cliente compatible con MCP. Consulta la documentación de tu cliente para instrucciones de configuración específicas. El servidor acepta conexiones mediante transporte stdio.

Herramientas disponibles

Bitcoin Stamps

get_stamp - Obtén información detallada sobre un stamp específico por ID
search_stamps - Busca stamps con varios filtros (creador, colección, etc.)
get_recent_stamps - Obtén los stamps creados más recientemente

Colecciones de Stamps

get_collection - Obtén información detallada sobre una colección específica
search_collections - Busca colecciones con filtros

Tokens SRC-20

get_token_info - Obtén información detallada sobre un token SRC-20 específico
search_tokens - Busca tokens SRC-20 con varios filtros

Configuración

El servidor se puede configurar mediante:

Archivo de configuración (formato JSON)
Variables de entorno
Argumentos de línea de comandos

Ejemplo de archivo de configuración

{
  "api": {
    "baseUrl": "https://stampchain.io/api",
    "timeout": 30000,
    "retries": 3
  },
  "logging": {
    "level": "info"
  },
  "registry": {
    "maxTools": 1000,
    "validateOnRegister": true
  }
}

Variables de entorno

STAMPCHAIN_API_URL - URL base de la API (predeterminado: https://stampchain.io/api)
STAMPCHAIN_LOG_LEVEL - Nivel de registro (debug, info, warn, error)
STAMPCHAIN_API_TIMEOUT - Tiempo de espera de la API en milisegundos

Uso desde línea de comandos

# Start with default configuration
npm run start

# Start with custom config file
npm run start -- --config config.json

# Start with debug logging
npm run start -- --log-level debug

# Show available tools
npm run tools

# Show version information
npm run version

Desarrollo

Scripts

npm run dev - Inicia el servidor de desarrollo con recarga automática
npm run build - Compila el proyecto TypeScript
npm run test - Ejecuta todas las pruebas
npm run test:watch - Ejecuta pruebas en modo de observación
npm run test:coverage - Ejecuta pruebas con informe de cobertura
npm run typecheck - Verificación de tipos de TypeScript
npm run format - Formatea el código con Prettier
npm run validate - Suite completa de validación

Pruebas

El proyecto incluye una cobertura de pruebas exhaustiva:

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode during development
npm run test:watch

Estructura del proyecto

src/
├── api/           # API client and related utilities
├── config/        # Configuration management
├── interfaces/    # TypeScript interfaces
├── protocol/      # MCP protocol handlers
├── schemas/       # Zod validation schemas
├── tools/         # MCP tool implementations
├── utils/         # Utility functions
├── index.ts       # Main entry point
└── server.ts      # Server implementation

Referencia de la API

Parámetros de las herramientas

Todas las herramientas aceptan varios parámetros para filtrado y paginación:

limit - Número de resultados a devolver (predeterminado: 10, máximo: 100)
page - Número de página para paginación (predeterminado: 1)
sort - Campo de ordenación y dirección (por ejemplo, "created_desc")

Formato de respuesta

Todas las herramientas devuelven datos estructurados con:

success - Booleano que indica si la solicitud fue exitosa
data - Los datos solicitados (stamps, colecciones, tokens)
pagination - Información de paginación cuando corresponda
error - Detalles del error si la solicitud falló

Solución de problemas

Problemas comunes

Errores de compilación: Asegúrate de tener Node.js 18+ y ejecuta npm install primero
Problemas de conexión: Verifica que la API de Stampchain sea accesible
Integración con clientes MCP: Verifica que la ruta en tu archivo de configuración sea correcta

Depuración

Habilita el registro de depuración para ver información detallada:

npm run start -- --debug

O establece el nivel de registro en tu configuración:

{
  "logging": {
    "level": "debug"
  }
}

Desarrollo

Cobertura de pruebas

Este proyecto mantiene una cobertura de pruebas exhaustiva en múltiples áreas:

✅ Pruebas unitarias - Utilidades principales y funciones auxiliares
✅ Pruebas de integración - Funcionalidad del servidor MCP
✅ Validación de API - Garantiza compatibilidad con la API v2.3
✅ Validación de esquemas - Alineación de esquemas TypeScript y Zod
✅ Multiplataforma - Probado en Ubuntu, Windows y macOS
✅ Multi-versión - Soporte para Node.js 18.x, 20.x y 22.x
✅ Pruebas con API real - Valida contra la API v2.3 de Stampchain en vivo

Comandos de prueba detallados

# Run specific test suites
npm run test:unit         # Unit tests for utilities and helpers
npm run test:integration  # Integration tests for MCP server
npm run test:api         # API validation tests (v2.3 compatibility)
npm run test:tools       # Tool functionality tests
npm run test:schemas     # Schema validation tests

# Advanced testing options
npm run test:ui          # Run tests in UI mode (interactive)
npm run test:ci          # CI test run (includes coverage)
npm run validate         # Full validation (schema + typecheck + format + tests)

Flujo de trabajo de desarrollo

Instala las dependencias: npm install
Inicia el servidor de desarrollo: npm run dev
Ejecuta pruebas en modo de observación: npm run test:watch
Valida antes de confirmar: npm run validate

Contribuciones

Haz un fork del repositorio
Crea una rama de funcionalidad: git checkout -b feature/new-feature
Realiza tus cambios
Ejecuta las pruebas: npm test
Confirma tus cambios: git commit -am 'Add new feature'
Sube a la rama: git push origin feature/new-feature
Envía una solicitud de extracción

Estilo de código

Usa TypeScript para todo el código nuevo
Sigue las pautas del modo estricto de TypeScript
Escribe pruebas para nuevas funcionalidades
Actualiza la documentación según sea necesario
Ejecuta npm run validate antes de enviar solicitudes de extracción

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Soporte

Problemas: Problemas de GitHub
Documentación: Documentación de la API de Stampchain
Comunidad: Telegram @BitcoinStamps

Registro de cambios

v0.2.0

Compatibilidad con Stampchain API v2.3: Esquemas y validación actualizados para la API más reciente
Pruebas mejoradas: Suite de pruebas exhaustiva con validación CI multiplataforma
Documentación mejorada: README profesional con insignias de estado y mejor organización
Desarrollo simplificado: Canal de validación optimizado (TypeScript + Prettier)
Correcciones de errores: Problemas de CI resueltos y mejoras en la validación de esquemas

v0.1.0

Lanzamiento inicial
Herramientas básicas de Bitcoin Stamps, Colecciones y SRC-20
Integración con clientes MCP
Suite de pruebas exhaustiva

Stampchain MCP Server

Documentación