# Godot MCP Gateway

[English](README.md) | [简体中文](README.zh-CN.md)

One Godot editor, multiple AI coding agents.

Godot MCP Gateway is a local control plane that lets Codex, Claude Code,
OpenCode, Pi, and other MCP clients share a single Godot editor safely. Each
client keeps an independent MCP session while one machine-wide Gateway owns
editor discovery, request routing, write scheduling, playtest access, the Godot
LSP connection, and reconnects.

> **Project status:** early development. The v1 Gateway topology, heterogeneous
> batch execution, and editor activity UI are implemented, but the project has
> not yet published a stable release.

## Why a Gateway?

Most Godot MCP integrations start one server and claim one editor port for every
AI client. That model becomes fragile when several agents work on the same
project. This project separates agent sessions from the editor connection:

```text
Codex -------- stdio shim --\
Claude Code -- stdio shim ---+-- local IPC -- Gateway -- WebSocket -- Godot Editor
OpenCode ----- stdio shim ---/                   |-- Playtest Runtime
Pi ----------- stdio shim --/                    `-- Godot LSP
```

The Godot plugin connects outward to the Gateway. Agents never claim Godot port
pools or connect directly to the editor.

## Highlights

- **Multi-agent sessions:** every MCP client has its own identity, lifecycle,
  and activity stream.
- **One editor connection:** the Gateway owns editor, runtime, and LSP routing.
- **Ordered writes:** editor mutations from different agents are scheduled FIFO.
- **Cross-tool batches:** `batch` runs heterogeneous MCP tools sequentially,
  stops on failure, and prevents other agents' writes from interleaving.
- **Visible operations:** the Godot Dock shows connected agents, queued and
  running work, batch progress, and recent results.
- **Editor focus:** successful mutations can select and focus the affected node.
- **Full toolkit base:** the upstream Godot tool catalogue remains available
  through the Gateway architecture.

## Requirements

- Godot 4.2 or newer
- Node.js 22 or newer
- npm

## Run from source

Clone and build the repository:

```bash
git clone https://github.com/di404/godot-mcp-gateway.git
cd godot-mcp-gateway
npm install
npm run build
```

Copy `addons/godot_mcp_gateway/` into your Godot project's `addons/` directory,
then enable **Godot MCP Gateway** under **Project Settings → Plugins**.

Start the machine-wide Gateway in a terminal and leave it running:

```bash
npm run start:gateway
```

Configure each MCP client to launch its own stdio shim. Replace
`/absolute/path/to/godot-mcp-gateway` with the clone's absolute path:

```json
{
  "mcpServers": {
    "godot-mcp-gateway": {
      "command": "node",
      "args": [
        "/absolute/path/to/godot-mcp-gateway/packages/server/dist/index.js",
        "stdio"
      ],
      "env": {
        "GODOT_MCP_PROJECT_PATH": "/absolute/path/to/your-godot-project"
      }
    }
  }
}
```

If the MCP client starts in the Godot project root,
`GODOT_MCP_PROJECT_PATH` can be omitted. Set `GODOT_MCP_AGENT_NAME` to override
the agent label shown in the Dock.

## Batch example

The `batch` tool accepts ordinary registered tool calls:

```json
{
  "calls": [
    {
      "tool": "scene_get_tree",
      "arguments": { "max_depth": 1 }
    },
    {
      "tool": "project_get_settings",
      "arguments": { "prefix": "application/" }
    }
  ]
}
```

Calls run in order through the normal validation and tool pipeline. Execution
stops at the first failed or cancelled step, and remaining steps are marked
`skipped`. Nested batches and output references are not supported in v1.

## Repository layout

- `addons/godot_mcp_gateway/` — Godot editor plugin, tool handlers, and Dock.
- `packages/server/` — Gateway process, stdio MCP surface, IPC, tool catalogue,
  scheduling, runtime routing, and LSP ownership.
- `docs/` — architecture, protocol, contributor, compatibility, and local
  testing documentation.

The repository root is also a small Godot project for developing and exercising
the plugin. Start with the [documentation index](docs/README.md) for deeper
guides.

## Current v1 boundaries

- One Gateway accepts one Godot editor and one active playtest runtime.
- The Gateway is started manually and runs in the foreground.
- A batch is failure-stop, with each mutation retaining its own Undo step.
- Nested batches and step-output references are intentionally deferred.

## Attribution and license

This project is an active fork of NPGameDev's
[Godot MCP Toolkit](https://github.com/NPGameDev/godot-mcp-toolkit) and
[Godot MCP Server](https://github.com/NPGameDev/godot-mcp-server). Their mature
tool catalogue and editor integration form the feature base; this fork changes
the connection topology around them.

Source code is available under the [MIT License](LICENSE). See
[ATTRIBUTIONS.md](ATTRIBUTIONS.md) for preserved upstream notices and third-party
acknowledgements. Inherited upstream artwork is development material and is not
licensed as this fork's independent brand asset; replace it before distributing
a branded release.