MCP SGF Server

Processa arquivos SGF (Smart Game Format) para extrair informações de jogos e gerar diagramas visuais do tabuleiro.

Documentação

MCP SGF Server

Um servidor Model Context Protocol (MCP) para processar arquivos SGF (Smart Game Format). Extraia informações do jogo e gere diagramas visuais do tabuleiro.

Recursos

Extraia informações abrangentes do jogo de arquivos SGF
Gere diagramas visuais do tabuleiro com temas e formatos personalizáveis
Alto desempenho: ≤200ms para informações do jogo, ≤500ms para diagramas
Validação robusta com tratamento detalhado de erros
Modo estrito TypeScript com 100% de segurança de tipos
91,73% de cobertura de testes com 139 testes abrangentes
Múltiplos formatos de saída: suporte a PNG e SVG
Temas personalizáveis: estilos clássico, moderno e minimalista

Início Rápido

NPX (Recomendado)

Inicie o servidor MCP instantaneamente sem instalação:

npx mcp-sgf

O servidor iniciará e aguardará conexões do protocolo MCP no stdio.

Instalação

Instale globalmente para uso repetido:

npm install -g mcp-sgf
mcp-sgf

Configuração de Desenvolvimento

Clone e configure para desenvolvimento:

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

Configuração do Cliente

Para usar este servidor com clientes compatíveis com MCP (Claude Desktop, etc.), adicione a seguinte configuração:

Configuração do Claude Desktop (claude_desktop_config.json):

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

Alternativa com instalação local:

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

Uso

O servidor MCP SGF fornece duas ferramentas principais que podem ser chamadas via protocolo MCP:

1. Extrair Informações do Jogo (`get-sgf-info`)

Extraia metadados abrangentes de arquivos SGF, incluindo informações dos jogadores, regras do jogo e 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])"
  }
}

Resposta:

{
  "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. Gerar Diagramas do Tabuleiro (`get-sgf-diagram`)

Crie diagramas visuais do tabuleiro mostrando posições do jogo com aparência personalizável.

{
  "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"
  }
}

Resposta:

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

A resposta inclui dados de imagem codificados em base64 com o tipo MIME especificado.

Opções de Configuração

Ferramenta de Informações do Jogo

Parâmetro	Tipo	Obrigatório	Descrição
`sgfContent`	string	✓	Conteúdo completo do arquivo SGF

Ferramenta de Diagrama

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`sgfContent`	string	✓	-	Conteúdo completo do arquivo SGF
`moveNumber`	number	✗	final	Movimento específico a exibir (base 1)
`startMove`	number	✗	-	Início do intervalo de movimentos (base 1)
`endMove`	number	✗	-	Fim do intervalo de movimentos (base 1)
`width`	number	✗	600	Largura da imagem (100-2000)
`height`	number	✗	600	Altura da imagem (100-2000)
`coordLabels`	boolean	✗	true	Mostrar rótulos de coordenadas
`moveNumbers`	boolean	✗	true	Mostrar números dos movimentos
`theme`	string	✗	classic	Tema visual
`format`	string	✗	png	Formato de saída

Temas Suportados

classic: Tabuleiro de madeira tradicional com pedras clássicas
modern: Aparência limpa e contemporânea
minimal: Design simplificado para clareza

Formatos Suportados

png: Formato raster, ideal para visualização e compartilhamento
svg: Formato vetorial, escalável e editável

Tamanhos de Tabuleiro Suportados

Intervalo: tabuleiros de 1×1 a 361×361
Comuns: 9×9, 13×13, 19×19
Automático: detecção de tamanho a partir do conteúdo SGF

Desenvolvimento

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

Integração com o Cliente

Exemplos JSON do Protocolo MCP

Ao integrar programaticamente, use estes formatos de mensagem JSON:

Listar Ferramentas Disponíveis:

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

Chamar Ferramenta Get SGF Info:

{
  "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])"
    }
  }
}

Chamar Ferramenta Get SGF Diagram:

{
  "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"
    }
  }
}

Estrutura do Projeto

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

Testes

# 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

Garantia de Qualidade

TypeScript: Modo estrito com 100% de cobertura de tipos
ESLint: Zero avisos com regras estritas
Prettier: Formatação de código consistente
Vitest: Limite de 95% de cobertura aplicado
Desempenho: Metas de tempo de resposta validadas

Tratamento de Erros

O servidor fornece tratamento abrangente de erros com tipos de erro específicos:

Tipos de Erro

Tipo	Descrição
`INVALID_FORMAT`	O conteúdo SGF não está em formato válido
`INVALID_PARAMETERS`	Parâmetros inválidos ou ausentes
`PARSING_ERROR`	Falha ao analisar o conteúdo SGF
`UNSUPPORTED_GAME`	Tipo de jogo não suportado
`FILE_TOO_LARGE`	O arquivo SGF excede os limites de tamanho

Exemplo de Resposta de Erro

{
  "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": {}
  }
}

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Documentação

Referência de Ferramentas: Documentação completa da API
Esquema OpenAPI: Especificação legível por máquina
Model Context Protocol: Especificação MCP

MCP SGF Server

Documentação

MCP SGF Server

Recursos

Início Rápido

NPX (Recomendado)

Instalação

Configuração de Desenvolvimento

Configuração do Cliente

Uso

1. Extrair Informações do Jogo (get-sgf-info)

2. Gerar Diagramas do Tabuleiro (get-sgf-diagram)

Opções de Configuração

Ferramenta de Informações do Jogo

Ferramenta de Diagrama

Temas Suportados

Formatos Suportados

Tamanhos de Tabuleiro Suportados

Desenvolvimento

Scripts

Integração com o Cliente

Exemplos JSON do Protocolo MCP

Estrutura do Projeto

Testes

Garantia de Qualidade

Tratamento de Erros

Tipos de Erro

Exemplo de Resposta de Erro

Licença

Documentação

1. Extrair Informações do Jogo (`get-sgf-info`)

2. Gerar Diagramas do Tabuleiro (`get-sgf-diagram`)