MCP SGF Server

Procesa archivos SGF (Smart Game Format) para extraer información de partidas y generar diagramas visuales del tablero.

Documentación

Servidor MCP SGF

Un servidor Model Context Protocol (MCP) para procesar archivos SGF (Smart Game Format). Extrae información de partidas y genera diagramas visuales de tablero.

Características

Extrae información completa de la partida de archivos SGF
Genera diagramas visuales de tablero con temas y formatos personalizables
Alto rendimiento: ≤200ms para información de partida, ≤500ms para diagramas
Validación robusta con manejo detallado de errores
Modo estricto de TypeScript con 100% de seguridad de tipos
91.73% de cobertura de pruebas con 139 pruebas exhaustivas
Múltiples formatos de salida: soporte para PNG y SVG
Temas personalizables: estilos clásico, moderno y minimalista

Inicio Rápido

NPX (Recomendado)

Inicia el servidor MCP al instante sin instalación:

npx mcp-sgf

El servidor se iniciará y escuchará conexiones del protocolo MCP en stdio.

Instalación

Instala globalmente para uso repetido:

npm install -g mcp-sgf
mcp-sgf

Configuración de Desarrollo

Clona y configura para desarrollo:

git clone <repository-url>
cd mcp-sgf
npm install
npm run build
npm start

Configuración del Cliente

Para usar este servidor con clientes compatibles con MCP (Claude Desktop, etc.), añade la siguiente configuración:

Configuración de Claude Desktop (claude_desktop_config.json):

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

Alternativa con instalación local:

{
  "mcpServers": {
    "sgf": {
      "command": "mcp-sgf"
    }
  }
}

Uso

El servidor MCP SGF proporciona dos herramientas principales que se pueden invocar mediante el protocolo MCP:

1. Extraer Información de la Partida (`get-sgf-info`)

Extrae metadatos completos de archivos SGF, incluyendo información de jugadores, reglas de juego y resultados.

{
  "tool": "get-sgf-info",
  "arguments": {
    "sgfContent": "(;FF[4]GM[1]SZ[19]PB[Lee Sedol]PW[AlphaGo]BR[9p]WR[-]KM[7.5]RE[W+R]DT[2016-03-09];B[pd];W[dp];B[cd];W[qp])"
  }
}

Respuesta:

{
  "success": true,
  "data": {
    "gameInfo": {
      "playerBlack": "Lee Sedol",
      "playerWhite": "AlphaGo",
      "blackRank": "9p",
      "whiteRank": "-",
      "boardSize": 19,
      "komi": 7.5,
      "result": "W+R",
      "date": "2016-03-09",
      "fileFormat": 4,
      "gameType": 1
    },
    "metadata": {
      "totalMoves": 4,
      "boardSize": 19,
      "hasValidStructure": true
    },
    "warnings": []
  }
}

2. Generar Diagramas de Tablero (`get-sgf-diagram`)

Crea diagramas visuales de tablero que muestran posiciones de juego con apariencia personalizable.

{
  "tool": "get-sgf-diagram", 
  "arguments": {
    "sgfContent": "(;FF[4]GM[1]SZ[19];B[pd];W[dp];B[cd];W[qp];B[ed];W[fq])",
    "moveNumber": 4,
    "width": 800,
    "height": 800,
    "theme": "modern",
    "coordLabels": true,
    "moveNumbers": false,
    "format": "png"
  }
}

Respuesta:

{
  "success": true,
  "data": {
    "mimeType": "image/png",
    "width": 800,
    "height": 800,
    "movesCovered": 4,
    "boardSize": 19,
    "parameters": {
      "moveNumber": 4,
      "format": "png",
      "theme": "modern"
    }
  }
}

La respuesta incluye datos de imagen codificados en base64 con el tipo MIME especificado.

Opciones de Configuración

Herramienta de Información de Partida

Parámetro	Tipo	Requerido	Descripción
`sgfContent`	string	✓	Contenido completo del archivo SGF

Herramienta de Diagramas

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`sgfContent`	string	✓	-	Contenido completo del archivo SGF
`moveNumber`	number	✗	final	Movimiento específico a mostrar (basado en 1)
`startMove`	number	✗	-	Inicio del rango de movimientos (basado en 1)
`endMove`	number	✗	-	Fin del rango de movimientos (basado en 1)
`width`	number	✗	600	Ancho de imagen (100-2000)
`height`	number	✗	600	Alto de imagen (100-2000)
`coordLabels`	boolean	✗	true	Mostrar etiquetas de coordenadas
`moveNumbers`	boolean	✗	true	Mostrar números de movimientos
`theme`	string	✗	classic	Tema visual
`format`	string	✗	png	Formato de salida

Temas Soportados

classic: Tablero de madera tradicional con piedras clásicas
modern: Apariencia limpia y contemporánea
minimal: Diseño simplificado para mayor claridad

Formatos Soportados

png: Formato rasterizado, ideal para visualizar y compartir
svg: Formato vectorial, escalable y editable

Tamaños de Tablero Soportados

Rango: Tableros de 1×1 a 361×361
Comunes: 9×9, 13×13, 19×19
Automático: Detección de tamaño desde el contenido SGF

Desarrollo

Scripts

npm run build       # Build TypeScript to JavaScript
npm run dev         # Development mode with watch
npm test           # Run all tests with coverage
npm run lint       # ESLint checking
npm run format     # Prettier formatting
npm run type-check # TypeScript type checking

Integración con Clientes

Ejemplos JSON del Protocolo MCP

Al integrar programáticamente, usa estos formatos de mensajes JSON:

Listar Herramientas Disponibles:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Llamar a la Herramienta Obtener Información SGF:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get-sgf-info",
    "arguments": {
      "sgfContent": "(;FF[4]GM[1]SZ[19]PB[Lee Sedol]PW[AlphaGo]BR[9p]WR[-]KM[7.5]RE[W+R]DT[2016-03-09];B[pd];W[dp];B[cd];W[qp])"
    }
  }
}

Llamar a la Herramienta Obtener Diagrama SGF:

{
  "jsonrpc": "2.0", 
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get-sgf-diagram",
    "arguments": {
      "sgfContent": "(;FF[4]GM[1]SZ[19];B[pd];W[dp];B[cd];W[qp];B[ed];W[fq])",
      "moveNumber": 4,
      "width": 800,
      "height": 800,
      "theme": "modern",
      "format": "png"
    }
  }
}

Estructura del Proyecto

mcp-sgf/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/                # MCP tool implementations
│   │   ├── getSgfInfo.ts     # Game information extraction
│   │   └── getSgfDiagram.ts  # Diagram generation
│   ├── utils/                # Utility functions
│   │   ├── sgfParser.ts      # SGF parsing logic
│   │   ├── diagramRenderer.ts # Image generation
│   │   └── validation.ts     # Input validation
│   └── types/
│       └── sgf.ts           # TypeScript type definitions
├── tests/                   # Comprehensive test suite
├── docs/                    # Documentation
└── package.json            # Dependencies and scripts

Pruebas

# Run all tests
npm test

# Run specific test suite
npm test tests/getSgfInfo.test.ts

# Run with coverage report
npm test -- --coverage

# Run performance tests
npm test tests/performance.test.ts

Aseguramiento de Calidad

TypeScript: Modo estricto con 100% de cobertura de tipos
ESLint: Cero advertencias con reglas estrictas
Prettier: Formato de código consistente
Vitest: Umbral de cobertura del 95% aplicado
Rendimiento: Objetivos de tiempo de respuesta validados

Manejo de Errores

El servidor proporciona manejo exhaustivo de errores con tipos de error específicos:

Tipos de Error

Tipo	Descripción
`INVALID_FORMAT`	El contenido SGF no tiene un formato válido
`INVALID_PARAMETERS`	Parámetros inválidos o faltantes
`PARSING_ERROR`	Fallo al analizar el contenido SGF
`UNSUPPORTED_GAME`	Tipo de juego no soportado
`FILE_TOO_LARGE`	El archivo SGF excede los límites de tamaño

Ejemplo de Respuesta de Error

{
  "success": false,
  "error": {
    "type": "INVALID_FORMAT",
    "message": "Invalid SGF format. SGF files must start with '(' and end with ')' and contain at least one property.",
    "details": {}
  }
}

Licencia

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

Documentación

Referencia de Herramientas: Documentación completa de la API
Esquema OpenAPI: Especificación legible por máquina
Model Context Protocol: Especificación de MCP

MCP SGF Server

Documentación

Servidor MCP SGF

Características

Inicio Rápido

NPX (Recomendado)

Instalación

Configuración de Desarrollo

Configuración del Cliente

Uso

1. Extraer Información de la Partida (get-sgf-info)

2. Generar Diagramas de Tablero (get-sgf-diagram)

Opciones de Configuración

Herramienta de Información de Partida

Herramienta de Diagramas

Temas Soportados

Formatos Soportados

Tamaños de Tablero Soportados

Desarrollo

Scripts

Integración con Clientes

Ejemplos JSON del Protocolo MCP

Estructura del Proyecto

Pruebas

Aseguramiento de Calidad

Manejo de Errores

Tipos de Error

Ejemplo de Respuesta de Error

Licencia

Documentación

1. Extraer Información de la Partida (`get-sgf-info`)

2. Generar Diagramas de Tablero (`get-sgf-diagram`)