# 🔥 Forge Engine — MCP Server

> Let AI agents (Claude, Antigravity, Cursor, etc.) fully control the Godot game engine.

## What is this?

This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects to a running Forge Engine (Godot fork) instance over WebSocket. It exposes the Forge Protocol as MCP tools, enabling any MCP-compatible AI agent to:

- 🌲 **Manipulate the scene tree** — Add, remove, move, duplicate nodes
- 🔍 **Inspect & modify properties** — Get/set any node property, connect signals
- 📸 **Capture viewport screenshots** — AI can "see" your game
- ▶️ **Run & debug your game** — Start, stop, breakpoints, variable inspection
- 📝 **Edit scripts** — Read and write GDScript/C# source code
- 🎮 **Simulate input** — Click, keyboard, drag in the editor
- 📦 **Manage assets** — Import files, create resources

## Quick Start

### 1. Install
```bash
npm install -g @forge-engine/mcp-server
```

### 2. Configure your AI client

Add to your MCP config (e.g., Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "forge-engine": {
      "command": "forge-mcp",
      "args": ["--port", "6550"]
    }
  }
}
```

### 3. Open Forge Engine (Godot fork) with your project

The MCP server will automatically connect to the running editor.

## Available Tools

| Tool | Description |
|------|-------------|
| `forge_get_scene_tree` | Get the full scene tree |
| `forge_add_node` | Add a node to the scene |
| `forge_remove_node` | Remove a node from the scene |
| `forge_get_properties` | Get all properties of a node |
| `forge_set_property` | Set a property on a node |
| `forge_screenshot` | Capture the viewport |
| `forge_run_project` | Run the game |
| `forge_stop_project` | Stop the game |
| `forge_get_script` | Get script source code |
| `forge_set_script` | Update script source code |
| `forge_execute_gdscript` | Run GDScript code in the editor |
| `forge_get_output` | Get console output |

## Protocol

This MCP server communicates with Forge Engine via the **Forge Protocol** — a WebSocket-based automation protocol inspired by Chrome DevTools Protocol. See the [Forge Protocol Spec](../docs/protocol-spec.md) for details.

## License

MIT — see [LICENSE](./LICENSE)