# Hermes WorldKit MCP

A separate, first-party MCP control server for WorldKit's Godot editor adapter. Hermes launches the Python process over stdio; the process also binds a localhost-only WebSocket endpoint. The optional Godot 4.6 `EditorPlugin` connects outbound, authenticates, and proves it opened the exact pinned project root.

## Vertical-slice capabilities

- Report bridge/editor status and capabilities.
- Summarize the currently edited scene.
- List selected nodes in that scene.
- Select one existing node by an edited-scene-relative path.

There is deliberately no terminal, file writing, GDScript evaluation, generic method invocation, arbitrary property mutation, autoload, or runtime dependency.

## Install

```bash
git clone https://github.com/DeployFaith/Hermes_WorldKit_MCP.git
cd Hermes_WorldKit_MCP
uv sync
```

Copy `addons/worldkit_mcp_bridge` into the target Godot project's `addons/` directory, then enable **WorldKit MCP Bridge** in **Project Settings → Plugins**. The addon remains optional and must not be copied into WorldKit's base addon payload.

## Required configuration

Generate a random token and make the same value available to both the MCP process and the Godot editor environment:

```bash
export WORLDKIT_MCP_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export WORLDKIT_PROJECT_ROOT="/absolute/path/to/the/godot/project"
```

Optional server settings:

```bash
export WORLDKIT_MCP_WS_HOST="127.0.0.1"  # only loopback values are accepted
export WORLDKIT_MCP_WS_PORT="6506"  # use 0 only in tests that pass the chosen URI to Godot
export WORLDKIT_MCP_REQUEST_TIMEOUT="5.0"
```

The Godot addon reads `WORLDKIT_MCP_TOKEN` and, optionally, `WORLDKIT_MCP_WS_URL` (default `ws://127.0.0.1:6506`). The URL must be exactly `ws://127.0.0.1:<port>` or `ws://[::1]:<port>` with no credentials, path, query, or fragment. Start/restart Godot from an environment containing those values after changing them. Port `0` asks the Python bridge to choose an ephemeral port; it is intended for disposable tests because the selected port must then be supplied to Godot through `WORLDKIT_MCP_WS_URL`.

## Hermes stdio configuration example

```yaml
mcp_servers:
  worldkit:
    command: /absolute/path/to/Hermes_WorldKit_MCP/.venv/bin/worldkit-mcp
    args: []
    env:
      WORLDKIT_MCP_TOKEN: "replace-with-the-same-random-token-used-by-godot"
      WORLDKIT_PROJECT_ROOT: "/absolute/path/to/the/godot/project"
      WORLDKIT_MCP_WS_PORT: "6506"
```

The exact enclosing Hermes configuration keys may vary by installed Hermes version; the important stdio command and environment contract are shown above.

## Wire protocol

Protocol version 2 uses mutual challenge-response authentication. Python sends a random server nonce; Godot replies with a client nonce and HMAC-SHA256 proof; Python returns its own proof before either side accepts the session. Proofs are bound to the protocol version and canonical project root, but neither the shared token nor project root is transmitted during authentication. Browser-origin WebSockets, malformed envelopes, wrong versions, mismatched roots/secrets, unsolicited response IDs, and a second simultaneous editor are rejected.

Accepted requests and responses carry a UUID `request_id`; responses use `{ok, code, message, data}`. The Python bridge turns cancellation, timeouts, protocol failures, and disconnects into stable structured errors. A timed-out selection reports `SELECTION_OUTCOME_UNKNOWN` because Godot may have applied it before the response was lost.

`worldkit_scene_summary` and `worldkit_selected_nodes` return a `scene_token`. `worldkit_select_node(node_path, expected_scene_token)` requires that exact token before changing selection, preventing a command inspected against one scene from affecting a newly opened scene. Paths are canonical relative paths under the edited root. Absolute paths, subnames, empty or `.` components, backslashes, and any `..` segment are rejected before lookup. Internal nodes and nodes not owned by the current edited scene are excluded.

Scene inspection is bounded to 2,000 child-scan steps and 256 returned nodes; selected-node output is also capped at 256. The addon queues at most 64 requests and executes at most one request per editor frame.

## Development checks

```bash
uv run pytest -q
uv run ruff check .
uv run python -m worldkit_mcp.schema_dump
uv run python scripts/verify_godot_editor_e2e.py
```

The final command first verifies the executable is Godot 4.6, then launches a disposable **headless** editor and loads the real optional plugin. Its hostile fixture contains 2,005 wide root children plus a nested selectable node. The check completes mutual authentication, proves the scene summary stops at 256 returned nodes and reports truncation, changes the editor selection, reads it back, and proves that escaping, stale-scene, and noncanonical paths are rejected. It uses explicit runtime checks that remain active under `python -O`. Set `WORLDKIT_GODOT_BIN` if `godot` is not on `PATH`.

This headless editor integration check proves the transport and editor API behavior. It does not prove visible UI rendering or satisfy WorldKit's eventual human manual-QA gate.