MCP SDL3 Server

A Model Context Protocol (MCP) server that provides SDL3 API documentation, code examples, and reference information for AI assistants. Built with FastMCP for a clean, maintainable codebase.

Current Release: v0.1.0 - Early prerelease with 119 SDL3 functions and basic tooling!

Table of Contents

• Features
• Installation
  • Prerequisites
  • Quick Start
• Available Tools
• Usage with AI Assistants
• Development
• Contributing
  • For AI-Assisted Development
• Resources
• License

Features

• SDL3 Function Reference: Look up any SDL3 function with detailed API documentation
• Function Search: Search for functions by category or keyword
• SDL3 Code Examples: Browse and retrieve full working examples from examples.libsdl.org
• Example Search: Find examples by keyword across all categories
• SDL2 to SDL3 Migration Guides: Comprehensive migration guides for transitioning from SDL2 to SDL3

Installation

Prerequisites

• Python 3.10 or higher
• uv package manager (see installation guide)

Quick Start

Add to your AI assistant's MCP configuration:

{
  "mcpServers": {
    "mcp-sdl": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jvolden/mcp-sdl",
        "mcp-sdl"
      ]
    }
  }
}

Restart your AI assistant, and the SDL3 tools will be available.

Available Tools

API Reference Tools

• sdl_function_reference

  • Get detailed API documentation for a specific SDL3 function
  • Inputs:
    • function_name (string, required): Name of the SDL3 function (e.g., "SDL_Init", "SDL_CreateWindow")
  • Returns complete function signature, parameters, description, and code example

• sdl_search_functions

  • Search for SDL3 functions by category or keyword
  • Inputs:
    • query (string, optional): Search term or category name (e.g., "window", "audio", "render", "event"). If empty, returns all functions.
  • Returns list of matching functions with descriptions

Example Tools

• sdl_examples
  • Access SDL3 code examples from examples.libsdl.org
  • Inputs (all optional):
    • category (string): Category name (e.g., "renderer", "audio", "input")
    • example_id (string): Example identifier (e.g., "01-clear", "06-textures")
    • query (string): Search term (e.g., "texture", "gamepad")
  • Behavior:
    • No parameters: List all available categories with example counts
    • category only: List all examples in that category with descriptions
    • category + example_id: Get complete source code for that example
    • query only: Search for examples by keyword across all categories

Migration Tools

• sdl_migration
  • Access SDL2 to SDL3 migration guides and documentation
  • Inputs (all optional):
    • sdl2_name (string): SDL2 symbol name (e.g., "SDL_OpenAudio", "SDL_INIT_VIDEO", "SDL_AudioSpec")
    • header_name (string): SDL2 header name (e.g., "SDL_audio.h", "SDL_render.h", "SDL_video.h")
    • query (string): Search term (e.g., "removed", "renamed", "audio callback")
  • Behavior:
    • No parameters: List all available migration guide headers
    • sdl2_name only: Look up migration info for that specific SDL2 symbol
    • header_name only: Get complete migration guide for that header file
    • query only: Search across all migration guides for keywords

Usage with AI Assistants

Once configured, AI assistants can use this server to:

1. Look up SDL3 functions: "What does SDL_CreateRenderer do?"
2. Search for functions: "Show me all SDL3 rendering functions"
3. Browse code examples: "List available SDL3 renderer examples"
4. Get example source code: "Show me the SDL3 clear example from the renderer category"
5. Search examples: "Find SDL3 examples about textures"
6. Migrate from SDL2: "How do I migrate SDL_OpenAudio from SDL2 to SDL3?"
7. Search migration guides: "Show me all SDL2 functions that were removed in SDL3"

The server provides accurate API documentation and examples based on SDL3's official resources.

Development

Local Development Setup

# Clone and setup
git clone https://github.com/jvolden/mcp-sdl.git
cd mcp-sdl
uv sync

# Test the server
uv run mcp-sdl --help

# Run tests
uv run pytest

# Check test coverage
uv run pytest --cov --cov-report=term-missing

# Generate HTML coverage report
uv run pytest --cov --cov-report=html
# Open htmlcov/index.html in browser

# Lint code with ruff
uv run ruff check .

# Auto-fix linting issues
uv run ruff check --fix .

# Format code with ruff
uv run ruff format .

VS Code Setup

For VS Code users who want to test the MCP server locally:

1. Copy the template: cp mcp.json.template .vscode/mcp.json
2. Update the path: Change /path/to/your/mcp-sdl/project to your actual project directory
3. Restart VS Code: The MCP server will be available to GitHub Copilot

Example .vscode/mcp.json (create from template):

{
  "servers": {
    "mcp-sdl": {
      "type": "stdio", 
      "command": "uv",
      "args": ["--directory", "/your/actual/path/mcp-sdl", "run", "mcp-sdl"]
    }
  }
}

Alternatively, for published releases, you can use uvx:

{
  "servers": {
    "mcp-sdl": {
      "type": "stdio",
      "command": "uvx", 
      "args": ["--from", "git+https://github.com/jvolden/mcp-sdl", "mcp-sdl"]
    }
  }
}

Contributing

See CONTRIBUTING.md for detailed contribution guidelines.

For AI-assisted contributions, use the contributor skill in VS Code with GitHub Copilot.

Quick ways to contribute:

• Add more SDL3 functions to the reference database
• Expand code examples for different languages
• Improve documentation and examples
• Report issues or suggest features

For AI-Assisted Development

When using GitHub Copilot or other AI assistants in VS Code:

• Use contributor skill for general contribution guidance
• The mcp-developer skill automatically activates for any code changes
  • Ensures consistent module structure and patterns
  • Enforces 100% test coverage
  • Guides design decisions with trade-off analysis
  • Handles SDL3 API, examples, tests, and refactoring

See .github/skills/mcp-developer/ for implementation patterns.

Resources

• SDL3 Official Documentation
• SDL3 GitHub Repository
• SDL3 Migration Guide
• Model Context Protocol Documentation
• FastMCP Framework

License

MIT License - See LICENSE file for details