# Gameforge

> AI-powered game creation platform — learn how to build multi-agent pipelines with the Claude Agent SDK, MCP tool servers, and Google Gemini (Nano Banana + Lyria)

- **Type:** MCP server
- **Install:** `agentstack add mcp-robcost-gameforge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [robcost](https://agentstack.voostack.com/s/robcost)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [robcost](https://github.com/robcost)
- **Source:** https://github.com/robcost/gameforge

## Install

```sh
agentstack add mcp-robcost-gameforge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# GameForge - Agentic Game Creator

[](LICENSE)
[](https://nodejs.org/)

AI-powered game creation platform. Describe your game in plain English, watch an AI agent team build it collaboratively with live preview. Supports 2D games with Phaser 3 and 3D games with Three.js.

**GameForge is a learning repo** — it demonstrates how to build a multi-agent AI pipeline using the [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-agent-sdk) and [Google Gemini](https://ai.google.dev/) (Nano Banana for sprites, Lyria for music) to orchestrate a team of specialized AI agents that collaborate to produce working Phaser 3 (2D) and Three.js (3D) games.

## What You Can Learn

- **Claude Agent SDK patterns** — programmatic agent control, subagents, structured tool use
- **MCP tool servers** — building custom Model Context Protocol tools for agent capabilities
- **Multi-agent orchestration** — designing pipelines where agents hand off work to each other
- **Google Gemini Nano Banana** — generating game sprites and backgrounds from text descriptions
- **Google Lyria** — composing background music via the RealTime WebSocket API
- **Phaser 3 + Three.js game development** — scaffolding, code generation, and live preview for 2D and 3D games
- **Full-stack TypeScript** — Nx monorepo, Next.js, Express, WebSocket, Zustand

## How the AI Agent Pipeline Works

When a user describes a game in the chat, the orchestrator runs a sequential pipeline of specialized agents:

```
User Message
    │
    ▼
┌─────────────┐     Creates a Game Design Document (GDD)
│  Designer    │     with mechanics, art direction, and audio specs
└──────┬──────┘
       │
       ▼
┌─────────────┐     Generates sprites and backgrounds via
│  Artist      │     Google Gemini Nano Banana (runs if GDD has artDirection)
└──────┬──────┘
       │
       ▼
┌─────────────┐     Composes background music via Google Lyria
│  Musician    │     RealTime API (runs if GDD has musicDirection)
└──────┬──────┘
       │
       ▼
┌─────────────┐     Writes Phaser 3 or Three.js TypeScript code
│  Developer   │     using the GDD and generated assets via MCP file tools
└──────┬──────┘
       │
       ▼
┌─────────────┐     Launches the game in Playwright, captures
│  QA          │     screenshots, reports bugs back to the user
└──────┬──────┘
       │
       ▼
  User Feedback → loops back to Designer for iteration
```

Each agent uses the Claude Agent SDK with custom MCP tool servers. The orchestrator manages conversation context so agents can see prior work and iterate based on QA feedback.

## Key Files to Study

| File | What It Demonstrates |
|---|---|
| [`apps/orchestrator/src/agents/teamOrchestrator.ts`](apps/orchestrator/src/agents/teamOrchestrator.ts) | Pipeline orchestration — how agents are sequenced and handed context |
| [`apps/orchestrator/src/tools/gameToolServer.ts`](apps/orchestrator/src/tools/gameToolServer.ts) | MCP tool server — custom file tools that agents use to read/write game code |
| [`apps/orchestrator/src/agents/prompts/`](apps/orchestrator/src/agents/prompts/) | Agent system prompts — how each agent role is defined |
| [`apps/orchestrator/src/assets/assetGenerator.ts`](apps/orchestrator/src/assets/assetGenerator.ts) | Gemini Nano Banana integration — text-to-image generation for game sprites |
| [`apps/orchestrator/src/music/musicGenerator.ts`](apps/orchestrator/src/music/musicGenerator.ts) | Lyria RealTime API — WebSocket streaming for music composition |
| [`apps/orchestrator/src/tools/assetToolServer.ts`](apps/orchestrator/src/tools/assetToolServer.ts) | MCP tools for asset generation — `generate_asset`, `get_asset_status` |
| [`apps/orchestrator/src/tools/musicToolServer.ts`](apps/orchestrator/src/tools/musicToolServer.ts) | MCP tools for music generation — `generate_music`, `get_music_status` |
| [`docs/research/`](docs/research/) | API research notes — Claude Agent SDK, Gemini Nano Banana, Lyria, Phaser, Three.js |

## Architecture

```
apps/
  studio/          Next.js 16 frontend (port 4001) — chat + game preview
  orchestrator/    Express + WebSocket backend (port 4000) — AI agent pipeline

packages/
  shared-types/    TypeScript types shared across apps (messages, sessions, agents)
  game-templates/  Phaser 3 and Three.js starter templates for scaffolding

sessions/          Runtime game project data per session (gitignored)
```

## Quick Start

### Prerequisites

- Node.js 20+
- npm 10+
- An `ANTHROPIC_API_KEY` for Claude (required)
- A `GOOGLE_AI_API_KEY` for asset/music generation (optional)

### Setup

```bash
# Install dependencies
npm install

# Copy environment variables
cp .env.example .env.local
# Edit .env.local and set ANTHROPIC_API_KEY (and optionally GOOGLE_AI_API_KEY)

# Build shared packages
npx nx run-many -t build --projects=shared-types,game-templates
```

### Development

Run the orchestrator and studio in separate terminals:

```bash
# Terminal 1 — Orchestrator backend
npx nx serve orchestrator

# Terminal 2 — Studio frontend
npx nx dev studio
```

Then open http://localhost:4001 in your browser.

### Docker

```bash
# Start all services
docker-compose up

# Start with E2E test runner
docker-compose --profile e2e up
```

Health checks are configured for both services. The studio waits for the orchestrator to be healthy before starting.

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `ANTHROPIC_API_KEY` | Yes | Claude API key for the AI agent pipeline |
| `GOOGLE_AI_API_KEY` | No | Google AI API key — enables Artist (Nano Banana) and Musician (Lyria) agents |
| `ORCHESTRATOR_PORT` | No | Orchestrator HTTP/WS port (default: 4000) |
| `STUDIO_PORT` | No | Studio frontend port (default: 4001) |
| `NEXT_PUBLIC_ORCHESTRATOR_URL` | No | Studio → orchestrator REST URL (default: http://localhost:4000) |
| `NEXT_PUBLIC_ORCHESTRATOR_WS_URL` | No | Studio → orchestrator WebSocket URL (default: ws://localhost:4000) |

## Testing

Tests are mandatory for all code. Run them with:

```bash
# All tests
npx nx run-many -t test

# Single project
npx nx test studio
npx nx test orchestrator
npx nx test shared-types
npx nx test game-templates

# Type checking
npx nx run-many -t typecheck
```

## Building

```bash
# Build all projects
npx nx run-many -t build

# Build specific project
npx nx build orchestrator

# View the project dependency graph
npx nx graph
```

## Tech Stack

- **Frontend:** Next.js 16 (App Router), Tailwind CSS, Zustand
- **Backend:** Node.js, Express, WebSocket (ws), esbuild
- **Game Engines:** Phaser 3 (2D), Three.js (3D)
- **AI:** Claude Agent SDK (TypeScript), Claude Opus
- **Asset Generation:** Google Gemini Nano Banana (sprites, backgrounds)
- **Music Generation:** Google Lyria RealTime API (background music)
- **Build:** Nx monorepo, Vite (game projects)
- **Testing:** Vitest (unit/integration), Playwright (QA + E2E)

## Documentation

- [`docs/research/`](docs/research/) — API research notes on Claude Agent SDK, Gemini Nano Banana, Lyria, Phaser 3, Three.js
- [`docs/demo-walkthrough.md`](docs/demo-walkthrough.md) — Step-by-step walkthrough of a demo session

## Build Journey

This project was built iteratively in phases. See [`tasks/todo.md`](tasks/todo.md) for the full phase-by-phase development log, and [`tasks/lessons.md`](tasks/lessons.md) for lessons learned during the build.

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [robcost](https://github.com/robcost)
- **Source:** [robcost/gameforge](https://github.com/robcost/gameforge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-robcost-gameforge
- Seller: https://agentstack.voostack.com/s/robcost
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.