ragnar-johannsson/mcp-sgf

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

Quick Start

NPX (Recommended)

Start the MCP server instantly without installation:

npx mcp-sgf

The server will start and listen for MCP protocol connections on stdio.

Installation

Install globally for repeated use:

npm install -g mcp-sgf
mcp-sgf

Development Setup

Clone and set up for development:

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

Client Configuration

To use this server with MCP-compatible clients (Claude Desktop, etc.), add the following configuration:

Claude Desktop Configuration (claude_desktop_config.json):

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

Alternative with local installation:

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

Usage

The MCP SGF server provides two main tools that can be called via the MCP protocol:

1. Extract Game Information (get-sgf-info)

Extract comprehensive metadata from SGF files including player information, game rules, and results.

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

Response:

{
  "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. Generate Board Diagrams (get-sgf-diagram)

Create visual board diagrams showing game positions with customizable appearance.

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

Response:

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

The response includes base64-encoded image data with the specified MIME type.

Configuration Options

Game Information Tool

Diagram Tool

Supported Themes

• classic: Traditional wood board with classic stones
• modern: Clean, contemporary appearance
• minimal: Simplified design for clarity

Supported Formats

• png: Raster format, best for viewing and sharing
• svg: Vector format, scalable and editable

Supported Board Sizes

• Range: 1×1 to 361×361 boards
• Common: 9×9, 13×13, 19×19
• Automatic: Size detection from SGF content

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

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

License

MIT License - see file for details.

Documentation

• : Complete API documentation
• : Machine-readable specification
• Model Context Protocol: MCP specification