Labsco
ragnar-johannsson logo

MCP SGF Server

from ragnar-johannsson

Process SGF (Smart Game Format) files to extract game information and generate visual board diagrams.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#ai-image#git

MCP SGF Server

A Model Context Protocol (MCP) server for processing SGF (Smart Game Format) files. Extract game information and generate visual board diagrams with.

Features

  • Extract comprehensive game information from SGF files
  • Generate visual board diagrams with customizable themes and formats
  • High performance: ≤200ms for game info, ≤500ms for diagrams
  • Robust validation with detailed error handling
  • TypeScript strict mode with 100% type safety
  • 91.73% test coverage with 139 comprehensive tests
  • Multiple output formats: PNG and SVG support
  • Customizable themes: Classic, modern, and minimal styles

Development

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

Client Integration

MCP Protocol JSON Examples

When integrating programmatically, use these JSON message formats:

List Available Tools:

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

Call Get SGF Info Tool:

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

Call Get SGF Diagram Tool:

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

Project Structure

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

Testing

# 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

Quality Assurance

  • TypeScript: Strict mode with 100% type coverage
  • ESLint: Zero warnings with strict rules
  • Prettier: Consistent code formatting
  • Vitest: 95% coverage threshold enforced
  • Performance: Response time targets validated

Error Handling

The server provides comprehensive error handling with specific error types:

Error Types

TypeDescription
INVALID_FORMATSGF content is not valid format
INVALID_PARAMETERSInvalid or missing parameters
PARSING_ERRORFailed to parse SGF content
UNSUPPORTED_GAMEGame type not supported
FILE_TOO_LARGESGF file exceeds size limits

Example Error Response

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