Content
# mcp-boardgames
MCP server for board game rules, backed by a structured Markdown knowledge base generated from official PDFs. Designed for precise rule querying, edge-case resolution, and gameplay assistance.
## Current Status
This repository now exposes both:
- a local MCP server over `stdio`
- a remote MCP endpoint over HTTP at `/mcp`
The MCP transports are the primary and only public interface for this project.
## Run Locally
Prerequisites:
- Go 1.24 or newer
### MCP server (`stdio`)
Start the MCP server from the repository root:
```powershell
$env:BOARDGAME_RULES_PATH="boardgame_rules"
go run ./cmd/mcp-server
```
If `go` is not on your `PATH`, use the full binary path:
```powershell
$env:BOARDGAME_RULES_PATH="boardgame_rules"
& "C:\Program Files\Go\bin\go.exe" run ./cmd/mcp-server
```
This starts a local MCP server over standard input/output.
### Remote MCP server
Start the remote MCP server from the repository root:
```powershell
$env:BOARDGAME_RULES_PATH="boardgame_rules"
$env:PORT="8080"
go run ./cmd/server
```
If `go` is not on your `PATH`, use the full binary path:
```powershell
$env:BOARDGAME_RULES_PATH="boardgame_rules"
$env:PORT="8080"
& "C:\Program Files\Go\bin\go.exe" run ./cmd/server
```
The server starts on `http://localhost:8080` by default.
Available endpoints:
- `http://localhost:8080/mcp`: primary remote MCP endpoint using JSON-RPC 2.0 over HTTP with SSE support
## Run With Docker
Build the image from the repository root:
```powershell
docker build -t mcp-boardgames .
```
Run the container:
```powershell
docker run --rm -p 8080:8080 mcp-boardgames
```
The container includes the repository's `boardgame_rules/` directory and serves it from `/app/boardgame_rules` by default. The Docker image runs the remote MCP server process that exposes `/mcp`.
If you want to use a different local rules directory, mount it and override `BOARDGAME_RULES_PATH`:
```powershell
docker run --rm -p 8080:8080 `
-v "${PWD}\\boardgame_rules:/data/boardgame_rules:ro" `
-e BOARDGAME_RULES_PATH=/data/boardgame_rules `
mcp-boardgames
```
## Use The Remote MCP Endpoint
The remote MCP endpoint is exposed at:
```text
http://localhost:8080/mcp
```
This endpoint uses JSON-RPC 2.0, MCP session headers, and supports `text/event-stream` responses for streamable HTTP clients.
Minimal flow:
1. `POST /mcp` with `initialize`
2. Read `Mcp-Session-Id` from the response headers
3. `POST /mcp` with `notifications/initialized` using that session header
4. `POST /mcp` with `tools/list` or `tools/call`
5. Optionally use `Accept: text/event-stream` or `GET /mcp` for SSE-based MCP workflows
Example initialize request:
```powershell
curl -i -X POST "http://localhost:8080/mcp" `
-H "Content-Type: application/json" `
-H "Accept: application/json, text/event-stream" `
-d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"demo-client\",\"version\":\"1.0.0\"}}}"
```
Example `tools/call` request after initialization:
```powershell
curl -X POST "http://localhost:8080/mcp" `
-H "Content-Type: application/json" `
-H "Mcp-Session-Id: <session-id>" `
-d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"query_rules\",\"arguments\":{\"game\":\"twisted-cryptids\",\"topic\":\"setup\"}}}"
```
Example `tools/call` request asking for SSE:
```powershell
curl -N -X POST "http://localhost:8080/mcp" `
-H "Content-Type: application/json" `
-H "Accept: application/json, text/event-stream" `
-H "Mcp-Session-Id: <session-id>" `
-d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"query_rules\",\"arguments\":{\"game\":\"twisted-cryptids\",\"topic\":\"setup\"}}}"
```
Optional SSE stream open:
```powershell
curl -N "http://localhost:8080/mcp" `
-H "Accept: text/event-stream" `
-H "Mcp-Session-Id: <session-id>"
```
Current MCP tool:
- `query_rules`: search `boardgame_rules/<game>/` for relevant sections by topic
## Use With AI Agents
### Codex
Codex can use this project as:
- a local MCP server over `stdio`
- a remote MCP server over HTTP if your Codex MCP client is configured with a URL
Local `stdio` command:
```powershell
go run ./cmd/mcp-server
```
or, if needed:
```powershell
& "C:\Program Files\Go\bin\go.exe" run C:\Users\osman\OneDrive\Documentos\Gitkraken\mcp-boardgames\cmd\mcp-server
```
Remote MCP URL:
```text
http://localhost:8080/mcp
```
OpenAI documents Codex MCP configuration through the Codex CLI and shared config using MCP server URLs.
### Claude Desktop and other MCP clients
Claude Desktop can use this project as a local MCP server over `stdio`. Remote Claude MCP clients can use the `/mcp` endpoint over HTTP/SSE when exposed via HTTPS.
For local Claude Desktop use, point the MCP client at:
```powershell
go run ./cmd/mcp-server
```
For remote MCP use, expose this server over HTTPS and use:
```text
https://your-host.example.com/mcp
```
Anthropic documents remote MCP support on Claude products for supported plans. For Claude Desktop specifically, the most direct option remains local `stdio`.
### Claude Code
Claude Code supports both local MCP servers and remote MCP servers over HTTP/SSE.
Use local `stdio`:
```powershell
go run ./cmd/mcp-server
```
Or use the remote MCP URL:
```text
http://localhost:8080/mcp
```
Anthropic documents Claude Code MCP support for local command-based servers and HTTP/SSE MCP servers.
## Agent Setup Translation
Use `setup.sh` to translate the repository's canonical agent files into the conventions used by different agent tools.
Canonical sources:
- `AGENTS.md`
- `skills/*/SKILL.md`
Supported targets:
- `codex`
- `claude`
- `gemini`
- `copilot`
- `all`
Examples:
```powershell
bash ./setup.sh codex
bash ./setup.sh claude
bash ./setup.sh all
```
Generated outputs:
- `CLAUDE.md` and `.claude/skills/` for Claude Code
- `GEMINI.md` and `.agents/skills/` for Gemini CLI
- `.github/copilot-instructions.md` and `.github/skills/` for GitHub Copilot
- `.codex-setup.md` as a small Codex marker file
Skill handling:
- `setup.sh` does not copy the full canonical skill contents into each target directory
- For each translated skill, it creates a target-local `SKILL.md` stub
- Each stub points back to the canonical repo path, for example `skills/ingest-boardgame-manual/SKILL.md`
### What is needed for direct MCP registration
The repository already supports:
- local MCP over `stdio`
- remote MCP over HTTP at `/mcp`
- SSE responses on the remote MCP endpoint
The next transport upgrades, if needed, would be deeper MCP features such as resumable SSE streams, server-initiated notifications, and stricter remote-session semantics.
## Project Structure
- `cmd/mcp-server`: MCP `stdio` entrypoint
- `cmd/server`: remote MCP HTTP entrypoint
- `domain`: core domain entities and business rules
- `application`: use cases and application services
- `adapters`: infrastructure and external interfaces
## Domain Model
- `Game`: aggregate root for a board game and its rules
- `Rule`: topic-focused rule document loaded from Markdown
- `Section`: structured rule content within a rule
## Markdown Loading
- `adapters/filesystem`: loads a game's rules from `boardgame_rules/<game>/`
- Requires `00_metadata.yaml` in each game directory
- Reads `.md` rule files and splits them into sections based on Markdown headings
## Query Logic
- `application`: searches rule content by topic through an application service
- Matching is case-insensitive and limited to section title and section content
- Query results return only the relevant sections for the requested topic
## Server Interface
- `cmd/mcp-server`: starts a local MCP server over `stdio`
- MCP tool: `query_rules`
- `cmd/server`: starts the remote MCP server
- `POST /mcp`: primary remote MCP endpoint using JSON-RPC 2.0 over HTTP
- `GET /mcp`: optional SSE stream endpoint for MCP clients
- `BOARDGAME_RULES_PATH` sets the rules directory and defaults to `boardgame_rules`
- `PORT` sets the listening port and defaults to `8080`
- `ALLOWED_ORIGINS` optionally defines allowed HTTP origins for `/mcp` as a comma-separated list
- `Dockerfile`: builds a container image for the remote MCP server
## Skills
- `skills/ingest-boardgame-manual`: reusable workflow for converting official manual PDFs into repository-ready Markdown rule files and metadata
