mcp-defold

MCP server for driving Defold games through an in-game debug bridge. An MCP client can build the game, launch it, start a run, press inputs, and read the screen, state, and logs. Enough to playtest.

I built it because tests and simulators kept passing on builds of my own games that were actually broken or unplayable. Making the agent play the real build caught what they missed.

Tools

Related MCP server: mcp-rn-devtools

Install

git clone https://github.com/haksanlulz/mcp-defold
cd mcp-defold
npm install
cp projects.example.json projects.json   # register your game

Runs directly with tsx; no build step. Requires Node 18+ and PowerShell 7 (pwsh, cross-platform) for the run scripts.

Use it from an MCP client

{
  "mcpServers": {
    "defold": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-defold/index.ts"]
    }
  }
}

Env: MCP_DEFOLD_PROJECTS overrides the registry path; MCP_DEFOLD_DEFAULT picks the default project.

What your game has to provide

Two things, both on the game side (this server is just the client):

1. An in-game bridge: newline-delimited JSON over localhost TCP answering ping / screen / state / input / start / log / quit. Protocol in PROTOCOL.md; working skeleton in example/bridge.lua. Gate it behind a debug flag so it never ships in release builds.

2. A run script: builds with the bridge compiled in, launches the engine detached, prints bridge LIVE on <port>.

The screen is text on purpose: compose whatever view carries your game's state (an ASCII map + HUD for a roguelike, a score readout for an arcade game).

Limitations

• Screens are text frames composed by the game's bridge; there are no pixel screenshots.

• defold_input presses and releases each trigger; nothing can be held down.

• Bridge input drives the in-game controller, not the GUI front-end; defold_start exists because injected input can't get past menus.

• Run and test scripts are invoked through pwsh; there is no other runner.

Develop

npm test          # vitest: tool handlers against a fake in-process bridge (no Defold needed)
npm run smoke     # spawn the real server over stdio and exercise its error paths (offline)
npm run typecheck

AI assistance

This project was built with AI assistance (Claude). Correctness was established by the test suite (tool handlers driven end-to-end through a real MCP client against a fake in-process bridge that speaks the actual wire protocol, plus failure-path tests for the TCP layer), an offline smoke run that spawns the real server over stdio and checks its error paths (npm run smoke), and playtesting my own games with it. I review the code and am responsible for it.

License

MIT © Abishai James. Defold is a trademark of the Defold Foundation; this project is unofficial.