Skip to main content

Project Structure

Directory Tree​

openforge-mcp/
├── packages/
│ ├── mcp-server/ # MCP Server (TypeScript)
│ │ ├── src/
│ │ │ ├── index.ts # CLI entry point
│ │ │ ├── server.ts # MCP Server core (tool registration here)
│ │ │ ├── router.ts # Execute dispatch (unity/blender/godot)
│ │ │ ├── registry.ts # ToolDefinition type, mode management
│ │ │ ├── http.ts # HTTP API Server (port 19810)
│ │ │ ├── version-control.ts # Git-based save/load
│ │ │ ├── transaction.ts # Undo group management
│ │ │ ├── pipeline.ts # Blender <-> Unity file transfer
│ │ │ ├── recipe.ts # YAML recipe execution engine
│ │ │ ├── playtest.ts # AI playtest control
│ │ │ ├── copilot.ts # GitHub Copilot Dynamic Mode
│ │ │ ├── adapters/
│ │ │ │ ├── base.ts # TCP client base class
│ │ │ │ ├── unity.ts # Unity adapter (port 19800)
│ │ │ │ ├── blender.ts # Blender adapter (port 19801)
│ │ │ │ └── godot.ts # Godot adapter (port 19802)
│ │ │ ├── tools/
│ │ │ │ ├── unity/ # Unity tool definitions (*.ts)
│ │ │ │ ├── blender/ # Blender tool definitions (*.ts)
│ │ │ │ ├── godot/ # Godot tool definitions (*.ts)
│ │ │ │ └── system/ # System tool definitions (*.ts)
│ │ │ ├── cli/
│ │ │ │ ├── index.ts # CLI routing
│ │ │ │ ├── setup.ts # npx openforge-mcp setup
│ │ │ │ └── vscode-config.ts # VS Code config generation
│ │ │ └── __tests__/ # Vitest tests
│ │ ├── package.json
│ │ └── tsconfig.json
│ │
│ ├── unity-plugin/ # Unity Editor Plugin (C#)
│ │ ├── Editor/
│ │ │ ├── OpenForgeServer.cs # TCP server (port 19800)
│ │ │ ├── ToolExecutor.cs # Tool registration, dispatch, Undo management
│ │ │ ├── Tools/ # Tool implementations (1 category = 1 file)
│ │ │ └── UI/
│ │ │ └── SetupWindow.cs # Setup UI
│ │ └── package.json # UPM package definition
│ │
│ ├── blender-addon/ # Blender Addon (Python)
│ │ ├── __init__.py # Addon registration
│ │ ├── server.py # TCP server (port 19801)
│ │ ├── tool_executor.py # Tool registration, dispatch
│ │ ├── ui_panel.py # N-panel UI
│ │ ├── tools/ # Tool implementations (1 category = 1 file)
│ │ └── tests/ # pytest tests
│ │
│ └── godot-plugin/ # Godot Plugin (GDScript)
│ └── addons/openforge/
│ ├── plugin.cfg
│ ├── plugin.gd # EditorPlugin
│ ├── server.gd # TCP server (port 19802)
│ ├── tool_executor.gd # Tool dispatch
│ └── tools/ # Tool implementations
│
├── website/ # Docusaurus documentation site
│ ├── docs/ # Markdown pages
│ ├── src/pages/index.tsx # Top page
│ └── docusaurus.config.ts # Site configuration
│
├── README.md / README.ja.md
├── CONTRIBUTING.md / CONTRIBUTING.ja.md
└── LICENSE (MIT)

Communication Ports​

ServicePortProtocol
Unity Plugin19800JSON-RPC over TCP
Blender Addon19801JSON-RPC over TCP (length-prefixed)
Godot Plugin19802JSON-RPC over TCP (newline-delimited)
HTTP API19810REST (GET/POST)

Data Flow​

1. AI calls the "execute" tool
2. server.ts passes it to router.ts
3. router.ts selects the adapter based on target (unity/blender/godot)
4. The adapter sends a JSON-RPC request over TCP
5. The engine-side plugin receives the request
6. tool_executor looks up the handler by tool name and runs it
7. The result is returned as a JSON-RPC response
8. server.ts returns it to the AI

Mode Management (registry.ts)​

ModeBehavior
fullAll tools are available
essentialOnly tools in the ESSENTIAL_TOOLS set
dynamicDYNAMIC_BASE_TOOLS (8) + on-demand loading

In the execute handler of server.ts, when in dynamic mode, registry.loadToolOnDemand() is called if a tool has not been loaded yet.

Test Structure​

PackageFrameworkHow to Run
mcp-serverVitestnpx vitest run
blender-addonpytestcd tests && python -m pytest -v
unity-pluginUnity Editor onlyPlay Mode Test Runner
godot-pluginGodot only--

Code Style​

LanguageRules
TypeScriptstrict, ESM (import/export), .js extension in imports
C#OpenForge.Editor.Tools namespace, Undo required, main thread
PythonTOOLS dict, type hints, **kwargs acceptance
GDScript@tool, static functions, Dictionary input/output
All languagesNo emojis, no TODOs, minimal comments