# GameDev MCP Hub

**Version:** 0.1.0 · **Status:** active development

MCP hub that aggregates game-development MCP servers (Blender, Godot, GitHub, Obsidian, …) behind one interface for Claude, LM Studio, Cursor, and other MCP clients. Includes a local GUI, smart task routing, and SSE multi-client support.

## Quick start

**Prerequisites:** Node.js 20+

```bash
# Install
pnpm install   # or: npm install

# First-run config (.env, hub-config, mcp-servers)
pnpm setup     # or: npm run setup

# Edit secrets / enable servers
#   .env
#   config/mcp-servers.json

# Multi-client SSE hub + GUI (recommended)
pnpm start:sse   # after: pnpm build
# or: ./scripts/start.sh
```

- MCP SSE: `http://127.0.0.1:3000/sse`
- GUI: `http://127.0.0.1:3100` (port auto-scans 3100–3109)
- Stdio mode (single client): `pnpm start`

Windows: `scripts\start.bat` or `START_ALL.bat`.

## What works today

| Area | Status |
|------|--------|
| Downstream MCP via stdio (`ConnectionManager`) | Working |
| Tool namespacing (`server__tool`) | Working |
| Local GUI + WebSocket | Working |
| SSE multi-client (one Server per session) | Working |
| Smart Router (`hub__route_task`) | Wired |
| Skills as MCP resources (`skill://…`) | Working |
| Auth / rate limits | Optional (config + `HUB_API_KEY`) |

Enable servers in `config/mcp-servers.json`. Example configs ship as `*.example.json`.

## Architecture

```
AI clients (Claude / LM Studio / Cursor)
        │  MCP (stdio or SSE)
        ▼
 GameDev MCP Hub
  · Smart Router (hub__route_task)
  · Tool registry + search
  · GUI (localhost)
        │
        ▼
 Downstream MCP servers (Blender, Godot, GitHub, …)
```

## Configuration

| File | Purpose |
|------|---------|
| `.env` | API keys (see `.env.example`) |
| `config/hub-config.example.json` | Hub features, security, logging |
| `config/mcp-servers.example.json` | Downstream servers |
| `config/categories.json` | Tool categories |

`GITHUB_TOKEN` and `GITHUB_PERSONAL_ACCESS_TOKEN` are both accepted; the hub mirrors them when spawning servers.

By default HTTP/SSE/GUI bind to `127.0.0.1`. Set `security.bind_localhost_only: false` only if you understand the risk. Set `security.require_authentication: true` and `HUB_API_KEY` to protect GUI mutation endpoints.

## Scripts

```bash
pnpm build          # compile + copy GUI assets
pnpm start          # stdio transport
pnpm start:sse      # SSE multi-client
pnpm test           # unit tests
pnpm type-check
pnpm lint
```

## Docs

- [Configuration](docs/CONFIGURATION.md)
- [Architecture](docs/ARCHITECTURE_AND_CONNECTIONS.md)
- [GUI](docs/GUI.md)
- [LM Studio](docs/LM_STUDIO_SETUP.md)
- [Multi-client](docs/MULTI_CLIENT_SETUP.md)
- [API](docs/API.md)
- [Roadmap](ROADMAP.md)
- [Contributing](CONTRIBUTING.md)

Session notes and historical status dumps live under `archive/session-docs/`.

## License

MIT