How github-samples/turn-based-game-mcp works
1. This is a monorepo centered on a turn-based games demo with three runtime boundaries: a Next.js 15 web app, an MCP server, and a shared TypeScript package that contains the domain model and reusable logic. The architecture is intentionally split so the game rules and data contracts live outside both the UI and the AI server.
2. The shared/ package is the core domain layer. It defines game types, constants, storage abstractions, HTTP helpers, and the actual game engines for Tic-Tac-Toe and Rock Paper Scissors. Both the web app and MCP server depend on this package, making it the main source of truth for state shape and rules.
3. Within shared/, the games/ modules implement game-specific logic, while types/ and constants/ define cross-cutting contracts. The storage/ modules provide the persistence boundary: a generic game storage layer plus concrete adapters for SQLite and an MCP API client. This suggests the same domain model can be backed either by local storage or by API-driven access.
4. The web/ package is the user-facing frontend and API layer. It uses Next.js App Router under src/app/ for both pages and server routes, so the browser UI and HTTP endpoints are colocated in one runtime. The pages for each game render interactive boards and status panels, while API routes expose game creation, move submission, and MCP-facing endpoints.
5. The web UI is organized into reusable presentation components rather than game logic. components/games/ holds game-specific boards and info panels, components/ui/ holds generic shells like containers, controls, loading, and error states, and components/shared/ contains cross-game UI such as the MCP assistant panel and difficulty badge. This keeps rendering concerns separate from rules and storage.
6. The web API layer is the bridge between the browser and the domain layer. Routes under src/app/api/games/... handle game lifecycle actions such as listing games, creating games, and posting moves. The /mcp routes are explicitly for MCP integration and return sanitized data, indicating a deliberate trust boundary between public gameplay APIs and AI-friendly game state exposure.
7. The mcp-server/ package is the AI/runtime integration layer. It runs as a separate Node process over stdio and exposes MCP tools rather than a browser UI. Its handlers are split by concern: tool handlers, prompt handlers, elicitation handlers, and resource handlers, which map MCP protocol interactions onto game actions and game-state queries.
8. The MCP server includes dedicated AI strategy modules for each game. Tic-Tac-Toe and Rock Paper Scissors each have AI implementations plus security-focused tests, implying the server is responsible not just for move selection but also for guarding against invalid or unsafe game interactions. The server also uses an HTTP client utility, which indicates it can call back into the web API rather than manipulating state directly.
9. The main end-to-end data flow is: user interacts with the Next.js UI, UI calls the web API routes, the routes use shared game/storage logic, and the MCP server can independently query or act through the API via its own client layer. For AI-assisted play, the MCP server becomes the decision-making boundary, while the web app remains the presentation and orchestration layer.
10. Testing is a first-class architectural element across all packages. The repo contains extensive unit tests for domain logic, route tests for Next.js API endpoints, component tests for UI, and integration/security tests for the MCP server. Shared test utilities and setup files indicate the project is designed to validate the same game contract across packages and runtimes.
11. The repo also has a small amount of operational tooling that affects architecture: workspace-based package management, root TypeScript and ESLint configs, GitHub Actions CI, and a devcontainer for consistent local setup. The README and docs directory reinforce the intended package boundaries and describe MCP-specific architecture and testing guidelines.
12. For diagramming purposes, the key boxes are: shared domain/storage at the center; web UI and web API on one side; MCP server and AI tool handlers on the other; and SQLite/API client storage adapters beneath the shared layer. The most important arrows are UI → API routes → shared game logic/storage, and MCP server → web API/HTTP client → shared game logic, with sanitized MCP endpoints acting as the controlled integration seam.
Main entry points: games/index.ts Game engines · src/index.ts Shared entry · storage/index.ts Storage layer · route.ts Game API
Components 20
Shared domain
Core game model, rules, and storage abstractions reused by both runtimes.
- Shared entry · Top-level shared exports for the domain package.
shared/src/index.ts - Game types · Cross-cutting game state and game metadata types.
shared/src/types/game.ts - Game constants · Shared constants used across games and runtimes.
shared/src/constants/game-constants.ts - Game engines · Game-specific logic for Tic-Tac-Toe and Rock Paper Scissors.
shared/src/games/index.ts - Storage layer · Generic storage APIs and concrete adapters for local and API-backed access.
shared/src/storage/index.ts - HTTP utils · Reusable HTTP client helpers shared by storage and runtime layers.
shared/src/utils/index.ts - Test utils · Shared fixtures and database/test setup used across packages.
shared/src/testing/index.ts
Web app
Next.js UI and API routes for player interaction and MCP-facing endpoints.
- Game pages · App Router pages for browsing and playing each game.
web/src/app/games/tic-tac-toe/page.tsx - Game API · HTTP routes for game lifecycle, moves, and MCP-facing game access.
web/src/app/api/games/tic-tac-toe/route.ts - MCP routes · Game endpoints intended for MCP consumption with narrowed trust boundaries.
web/src/app/api/games/tic-tac-toe/mcp/route.ts - Game UI · Game-specific board and status components.
web/src/components/games/TicTacToeBoard.tsx - Shared UI · Cross-game UI such as assistant panels and common game chrome.
web/src/components/shared/MCPAssistantPanel.tsx - UI shell · Generic container, controls, loading, and error components.
web/src/components/ui/GameContainer.tsx - Web storage bridge · Web-side glue for talking to shared storage and API helpers.
web/src/lib/game-storage.ts
MCP server
Separate Node runtime exposing MCP tools, prompts, and AI move logic.
- MCP entry · Main Node process that exposes MCP capabilities over stdio.
mcp-server/src/server.ts - Tool handlers · MCP tool handlers that map protocol calls to game operations.
mcp-server/src/handlers/tool-handlers.ts - Prompt handlers · Prompt handlers for AI-driven interaction flows.
mcp-server/src/handlers/prompt-handlers.ts - Resource handlers · Resource and query handlers for exposing game state to clients.
mcp-server/src/handlers/resource-handlers.ts - AI engines · Game-specific AI and security checks for move selection.
mcp-server/src/ai/tic-tac-toe-ai.ts - HTTP client · Client used by the MCP server to query or act through the web API.
mcp-server/src/utils/http-client.ts
Connections 30
- Shared entry → Game types: exports · Re-exports the domain contracts.
- Shared entry → Game constants: exports · Re-exports shared constants.
- Shared entry → Game engines: exports · Re-exports the game engines.
- Shared entry → Storage layer: exports · Re-exports storage abstractions and adapters.
- Shared entry → HTTP utils: exports · Re-exports HTTP utilities.
- Shared entry → Test utils: exports · Re-exports test helpers.
- Game engines → Game types: uses · Game rules operate on shared state shapes.
- Game engines → Game constants: uses · Game logic depends on shared constants.
- Storage layer → Game types: stores · Persistence layer reads and writes domain state.
- Storage layer → HTTP utils: calls · API-backed storage uses shared HTTP helpers.
- Storage layer → Test utils: tested by · Storage layer is exercised by shared test utilities.
- Game pages → Game UI: renders · Pages assemble game-specific presentation components.
- Game pages → Shared UI: renders · Pages also use shared cross-game UI.
- Game pages → Game API: calls · Client-side gameplay flows submit actions through routes.
- Game API → Game engines: validates · Routes invoke shared game rules for moves and state changes.
- Game API → Storage layer: persists · Routes store and retrieve game state through shared storage.
- Game API → Web storage bridge: uses · Web API layer relies on app-side storage bridge.
- MCP routes → Game engines: exposes · Sanitized MCP routes surface domain state and actions.
- MCP routes → Storage layer: reads · MCP-facing routes read through the shared storage boundary.
- Shared UI → UI shell: composes · Shared UI is built on generic shell components.
- MCP entry → Tool handlers: registers · Server wires tool handlers into the MCP runtime.
- MCP entry → Prompt handlers: registers · Server wires prompt handlers into the MCP runtime.
- MCP entry → Resource handlers: registers · Server wires resource handlers into the MCP runtime.
- Tool handlers → Game engines: invokes · Tools map protocol calls onto shared game logic.
- Tool handlers → AI engines: selects moves · Tool handlers delegate to game-specific AI.
- Resource handlers → HTTP client: queries · Resources can fetch game state through the web API client.
- Prompt handlers → AI engines: guides · Prompt flows can shape AI-assisted play.
- AI engines → Game engines: reasons over · AI implementations depend on the same domain rules as the UI.
- AI engines → HTTP client: verifies · AI/security flows can call back through the HTTP client.
- HTTP client → Game API: calls · MCP server reaches the web runtime through HTTP endpoints.