# MCP SGF Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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 <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`):**
```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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sgfContent` | string | ✓ | Complete SGF file content |

### Diagram Tool

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `sgfContent` | string | ✓ | - | Complete SGF file content |
| `moveNumber` | number | ✗ | final | Specific move to display (1-based) |
| `startMove` | number | ✗ | - | Start of move range (1-based) |
| `endMove` | number | ✗ | - | End of move range (1-based) |
| `width` | number | ✗ | 600 | Image width (100-2000) |
| `height` | number | ✗ | 600 | Image height (100-2000) |
| `coordLabels` | boolean | ✗ | true | Show coordinate labels |
| `moveNumbers` | boolean | ✗ | true | Show move numbers |
| `theme` | string | ✗ | classic | Visual theme |
| `format` | string | ✗ | png | Output 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

```
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

| Type | Description |
|------|-------------|
| `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](LICENSE) file for details.

### Documentation

- **[Tool Reference](docs/tool-reference.md)**: Complete API documentation
- **[OpenAPI Schema](docs/openapi-schema.yaml)**: Machine-readable specification
- **[Model Context Protocol](https://modelcontextprotocol.io/)**: MCP specification