# github-samples/turn-based-game-mcp architecture

> Architecture diagram of the GitHub repository github-samples/turn-based-game-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/github-samples/turn-based-game-mcp
- Repository: https://github.com/github-samples/turn-based-game-mcp

## Overview

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: [`shared/src/games/index.ts`](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/games/index.ts) (Game engines), [`shared/src/index.ts`](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/index.ts) (Shared entry), [`shared/src/storage/index.ts`](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/storage/index.ts) (Storage layer), [`web/src/app/api/games/tic-tac-toe/route.ts`](https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/app/api/games/tic-tac-toe/route.ts) (Game API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_shared["Shared domain"]
  node_shared_index["Shared entry<br/>package entry<br/>[index.ts]"]
  node_shared_types["Game types<br/>domain contracts<br/>[game.ts]"]
  node_shared_constants["Game constants<br/>domain constants<br/>[game-constants.ts]"]
  node_shared_games["Game engines<br/>rules engine<br/>[index.ts]"]
  node_shared_storage["Storage layer<br/>persistence boundary<br/>[index.ts]"]
  node_shared_http["HTTP utils<br/>network helpers<br/>[index.ts]"]
  node_shared_testing["Test utils<br/>test support<br/>[index.ts]"]
end

subgraph group_group_web["Web app"]
  node_web_pages["Game pages<br/>Next.js pages<br/>[page.tsx]"]
  node_web_api["Game API<br/>route handlers<br/>[route.ts]"]
  node_web_mcp_api["MCP routes<br/>sanitized API<br/>[route.ts]"]
  node_web_ui_games["Game UI<br/>presentational UI<br/>[TicTacToeBoard.tsx]"]
  node_web_ui_shared["Shared UI<br/>presentational UI"]
  node_web_ui_shell["UI shell<br/>presentational UI<br/>[GameContainer.tsx]"]
  node_web_storage["Web storage bridge<br/>app adapter<br/>[game-storage.ts]"]
end

subgraph group_group_mcp["MCP server"]
  node_mcp_server["MCP entry<br/>stdio server<br/>[server.ts]"]
  node_mcp_tools["Tool handlers<br/>mcp tools<br/>[tool-handlers.ts]"]
  node_mcp_prompts["Prompt handlers<br/>mcp prompts<br/>[prompt-handlers.ts]"]
  node_mcp_resources["Resource handlers<br/>mcp resources"]
  node_mcp_ai["AI engines<br/>move strategy<br/>[tic-tac-toe-ai.ts]"]
  node_mcp_http["HTTP client<br/>api client<br/>[http-client.ts]"]
end

node_shared_index -->|"exports"| node_shared_types
node_shared_index -->|"exports"| node_shared_constants
node_shared_index -->|"exports"| node_shared_games
node_shared_index -->|"exports"| node_shared_storage
node_shared_index -->|"exports"| node_shared_http
node_shared_index -->|"exports"| node_shared_testing
node_shared_games -->|"uses"| node_shared_types
node_shared_games -->|"uses"| node_shared_constants
node_shared_storage -->|"stores"| node_shared_types
node_shared_storage -->|"calls"| node_shared_http
node_shared_storage -.->|"tested by"| node_shared_testing
node_web_pages -->|"renders"| node_web_ui_games
node_web_pages -->|"renders"| node_web_ui_shared
node_web_pages -->|"calls"| node_web_api
node_web_api -->|"validates"| node_shared_games
node_web_api -->|"persists"| node_shared_storage
node_web_api -->|"uses"| node_web_storage
node_web_mcp_api -->|"exposes"| node_shared_games
node_web_mcp_api -->|"reads"| node_shared_storage
node_web_ui_shared -->|"composes"| node_web_ui_shell
node_mcp_server -->|"registers"| node_mcp_tools
node_mcp_server -->|"registers"| node_mcp_prompts
node_mcp_server -->|"registers"| node_mcp_resources
node_mcp_tools -->|"invokes"| node_shared_games
node_mcp_tools -->|"selects moves"| node_mcp_ai
node_mcp_resources -->|"queries"| node_mcp_http
node_mcp_prompts -->|"guides"| node_mcp_ai
node_mcp_ai -->|"reasons over"| node_shared_games
node_mcp_ai -->|"verifies"| node_mcp_http
node_mcp_http -->|"calls"| node_web_api

click node_shared_index "https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/index.ts"
click node_shared_types "https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/types/game.ts"
click node_shared_constants "https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/constants/game-constants.ts"
click node_shared_games "https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/games/index.ts"
click node_shared_storage "https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/storage/index.ts"
click node_shared_http "https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/utils/index.ts"
click node_shared_testing "https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/testing/index.ts"
click node_web_pages "https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/app/games/tic-tac-toe/page.tsx"
click node_web_api "https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/app/api/games/tic-tac-toe/route.ts"
click node_web_mcp_api "https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/app/api/games/tic-tac-toe/mcp/route.ts"
click node_web_ui_games "https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/components/games/TicTacToeBoard.tsx"
click node_web_ui_shared "https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/components/shared/MCPAssistantPanel.tsx"
click node_web_ui_shell "https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/components/ui/GameContainer.tsx"
click node_web_storage "https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/lib/game-storage.ts"
click node_mcp_server "https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/server.ts"
click node_mcp_tools "https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/handlers/tool-handlers.ts"
click node_mcp_prompts "https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/handlers/prompt-handlers.ts"
click node_mcp_resources "https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/handlers/resource-handlers.ts"
click node_mcp_ai "https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/ai/tic-tac-toe-ai.ts"
click node_mcp_http "https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/utils/http-client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shared_index,node_shared_types,node_shared_constants,node_shared_games,node_shared_storage,node_shared_http,node_shared_testing toneBlue
class node_web_pages,node_web_api,node_web_mcp_api,node_web_ui_games,node_web_ui_shared,node_web_ui_shell,node_web_storage toneAmber
class node_mcp_server,node_mcp_tools,node_mcp_prompts,node_mcp_resources,node_mcp_ai,node_mcp_http toneMint
```

## Components

### Shared domain

Core game model, rules, and storage abstractions reused by both runtimes.

- [Shared entry](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/index.ts): package entry · Top-level shared exports for the domain package. · `shared/src/index.ts`
- [Game types](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/types/game.ts): domain contracts · Cross-cutting game state and game metadata types. · `shared/src/types/game.ts`
- [Game constants](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/constants/game-constants.ts): domain constants · Shared constants used across games and runtimes. · `shared/src/constants/game-constants.ts`
- [Game engines](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/games/index.ts): rules engine · Game-specific logic for Tic-Tac-Toe and Rock Paper Scissors. · `shared/src/games/index.ts`
- [Storage layer](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/storage/index.ts): persistence boundary · Generic storage APIs and concrete adapters for local and API-backed access. · `shared/src/storage/index.ts`
- [HTTP utils](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/utils/index.ts): network helpers · Reusable HTTP client helpers shared by storage and runtime layers. · `shared/src/utils/index.ts`
- [Test utils](https://github.com/github-samples/turn-based-game-mcp/blob/main/shared/src/testing/index.ts): test support · 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](https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/app/games/tic-tac-toe/page.tsx): Next.js pages · App Router pages for browsing and playing each game. · `web/src/app/games/tic-tac-toe/page.tsx`
- [Game API](https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/app/api/games/tic-tac-toe/route.ts): route handlers · HTTP routes for game lifecycle, moves, and MCP-facing game access. · `web/src/app/api/games/tic-tac-toe/route.ts`
- [MCP routes](https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/app/api/games/tic-tac-toe/mcp/route.ts): sanitized API · Game endpoints intended for MCP consumption with narrowed trust boundaries. · `web/src/app/api/games/tic-tac-toe/mcp/route.ts`
- [Game UI](https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/components/games/TicTacToeBoard.tsx): presentational UI · Game-specific board and status components. · `web/src/components/games/TicTacToeBoard.tsx`
- [Shared UI](https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/components/shared/MCPAssistantPanel.tsx): presentational UI · Cross-game UI such as assistant panels and common game chrome. · `web/src/components/shared/MCPAssistantPanel.tsx`
- [UI shell](https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/components/ui/GameContainer.tsx): presentational UI · Generic container, controls, loading, and error components. · `web/src/components/ui/GameContainer.tsx`
- [Web storage bridge](https://github.com/github-samples/turn-based-game-mcp/blob/main/web/src/lib/game-storage.ts): app adapter · 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](https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/server.ts): stdio server · Main Node process that exposes MCP capabilities over stdio. · `mcp-server/src/server.ts`
- [Tool handlers](https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/handlers/tool-handlers.ts): mcp tools · MCP tool handlers that map protocol calls to game operations. · `mcp-server/src/handlers/tool-handlers.ts`
- [Prompt handlers](https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/handlers/prompt-handlers.ts): mcp prompts · Prompt handlers for AI-driven interaction flows. · `mcp-server/src/handlers/prompt-handlers.ts`
- [Resource handlers](https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/handlers/resource-handlers.ts): mcp resources · Resource and query handlers for exposing game state to clients. · `mcp-server/src/handlers/resource-handlers.ts`
- [AI engines](https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/ai/tic-tac-toe-ai.ts): move strategy · Game-specific AI and security checks for move selection. · `mcp-server/src/ai/tic-tac-toe-ai.ts`
- [HTTP client](https://github.com/github-samples/turn-based-game-mcp/blob/main/mcp-server/src/utils/http-client.ts): api client · Client used by the MCP server to query or act through the web API. · `mcp-server/src/utils/http-client.ts`

## Connections

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