trackmcp
Back to directory
ragnar-johannsson

mcp-sgf

View on GitHub

An MCP server for handling SGF data

0 stars TypeScriptOthers Updated Jun 27, 2025

Documentation

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:

bash
npx mcp-sgf

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

Installation

Install globally for repeated use:

bash
npm install -g mcp-sgf
mcp-sgf

Development Setup

Clone and set up for development:

bash
git clone 
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`):

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

Alternative with local installation:

json
{
  "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.

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

json
{
  "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.

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

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

ParameterTypeRequiredDescription
`sgfContent`string✓Complete SGF file content

Diagram Tool

ParameterTypeRequiredDefaultDescription
`sgfContent`string✓-Complete SGF file content
`moveNumber`number✗finalSpecific move to display (1-based)
`startMove`number✗-Start of move range (1-based)
`endMove`number✗-End of move range (1-based)
`width`number✗600Image width (100-2000)
`height`number✗600Image height (100-2000)
`coordLabels`boolean✗trueShow coordinate labels
`moveNumbers`boolean✗trueShow move numbers
`theme`string✗classicVisual theme
`format`string✗pngOutput format

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

bash
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:

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

Call Get SGF Info Tool:

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

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

code
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

bash
# 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_FORMAT`SGF content is not valid format
`INVALID_PARAMETERS`Invalid or missing parameters
`PARSING_ERROR`Failed to parse SGF content
`UNSUPPORTED_GAME`Game type not supported
`FILE_TOO_LARGE`SGF file exceeds size limits

Example Error Response

json
{
  "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 LICENSE file for details.

Documentation

Frequently asked questions

What is mcp-sgf?

mcp-sgf is An MCP server for handling SGF data

How do I install mcp-sgf?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mcp-sgf open source?

Yes — it is hosted on GitHub at https://github.com/ragnar-johannsson/mcp-sgf.

Related MCP tools

modelcontextprotocolservers

Model Context Protocol Servers

90,051 TypeScript
bytedanceUI-TARS-desktop

The Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra

38,840 TypeScript
agentvlmvision+11
czlonkowskin8n-mcp

A MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you

22,825 TypeScript
mcpmcp-servern8n+1
glipsFigma-Context-MCP

MCP server to provide Figma layout information to AI coding agents like Cursor

15,766 TypeScript
aicursorfigma+2
elie222inbox-zero

The world's best AI personal assistant for email. Open source app to help you reach inbox zero fast.

12,148 TypeScript
aiemailnextjs+14
instantdbinstant

Instant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.

10,507 TypeScript

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP