Hermes_WorldKit_MCP: Instructions file for Codex

AGENTS.md

Repository identity

This repository is the separate, first-party WorldKit MCP control plane. It is not WorldKit Core and is not a base dependency of the WorldKit Godot adapter.

Hard boundaries

• Do not add this repository as a dependency of WorldKit Core or addons/hermes_worldkit.
• The Godot component is an optional EditorPlugin, installable at addons/worldkit_mcp_bridge.
• The Python process is a FastMCP stdio server for agents and a localhost-only WebSocket server for the outbound Godot editor connection.
• Require protocol-v2 mutual nonce/HMAC authentication and exact canonical project-root pinning before accepting a bridge client. Never transmit or log the raw token.
• Bind and connect only to literal loopback addresses. Reject browser Origin headers and require one atomically claimed editor client.
• Expose only explicit allowlisted operations. No terminal, shell, arbitrary file writes, GDScript evaluation, generic method invocation, unrestricted property mutation, runtime autoload, or project-setting mutation.
• Selection operations require the exact inspected scene token and may address only canonical, owned, non-internal nodes under the current edited-scene root.
• Bound editor-main-thread work, request queues, scene traversal, and selection serialization.
• Every request and response carries a request ID. Failures use stable structured error codes.
• Every MCP tool has a clear docstring and strict-client-friendly input schema: no Optional/union parameters and no anyOf.

Vertical-slice tool allowlist

• worldkit_status
• worldkit_capabilities
• worldkit_scene_summary
• worldkit_selected_nodes
• worldkit_select_node(node_path, expected_scene_token)

Validation discipline

Use the project-local .venv via uv. Run Python tests, lint, server import, and generated FastMCP schema checks. Godot headless parsing is valuable but is not editor E2E. Never claim editor E2E without actually running an editor and exercising the plugin.