Add a safe MCP controller action example #40

User and workflow

A developer using an MCP-capable agent wants to give it game controls through OpenController without hand-writing a one-off protocol bridge or exposing arbitrary controller commands to the model. The example should expose reviewed named actions and make a dry-run path usable without a native device.

Direct evidence

• Unity MCP issue #1408, opened 2026-09-21, says an agent can enter Play Mode, read the console, and take screenshots but cannot press keys or click controls. The author proposes runtime input tools, including bounded holds, and notes an initial Unity Input System/uGUI limitation.
• Codex issue #44074, opened 2026-09-09, requests duration-controlled inputs for an agent operating a game and requests input cleanup on cancellation and target loss.

These are reports and feature requests for other tools, not requests for OpenController specifically. They establish an agent workflow that crosses an MCP tool boundary, not demand for a new core API.

Repository gap and interpretation

The SDK already has named action maps and a runnable dry-run example in packages/core/src/actions/action-map.ts and examples/basic-dry-run/ai-agent-integration.ts. docs/ai-agent-integration.md documents action maps, but the repository has no MCP server example or tool-schema validation showing how an MCP client can call those reviewed actions. The proposed work is an integration example, not a new MCP package or broader computer-use implementation.

Proposed outcome

Add a small standalone example under examples/mcp-controller/ that exposes a fixed action map as MCP tools and defaults to the dry-run adapter. Provide a separate documented opt-in for a caller-supplied adapter so the example does not silently install or start a native driver.

Acceptance criteria

• Provide a runnable MCP server example using the official MCP TypeScript SDK and @opencontroller/core.
• Expose named, allowlisted action-map entries rather than arbitrary raw ControllerCommand JSON.
• Validate tool arguments and return structured success/error results without leaking local exception stacks by default.
• Default to dry-run and document how to opt into an already-configured adapter.
• Include a client-side or in-process smoke test that lists tools, invokes a valid action, rejects malformed/unknown action input, and observes the expected dry-run state.
• Document lifecycle cleanup with finally/disconnect and state clearly that MCP success only confirms the example's SDK path, not that a host or game consumed input.
• Keep the example scoped to examples/mcp-controller/ plus the minimum root check/test-script changes needed to validate it.

Tests and validation

Add a package-local smoke test using the dry-run adapter; run the example's typecheck/test command and the root example validation command if integrated into it. No API key or hardware should be required.

Non-goals

• No changes to Unity MCP, Codex Computer Use, core controller commands, or computer-use key/mouse injection.
• No unbounded arbitrary-command tool, remote server deployment, driver installation, or claim of game/window compatibility.

Confidence and limits

Low to medium. MCP is an observed integration surface in current agent tooling, and a concrete Unity MCP request describes missing game input. The sources do not identify OpenController as the desired provider, so this is an ecosystem-adoption hypothesis, not a demonstrated SDK defect.

Ownership and dependencies

Lane: new examples/mcp-controller/ files and package-local tests. The root Bun workspace includes examples/*, so the new package is auto-discovered, but adding the MCP SDK will require a root bun.lock update; root typecheck/test scripts or tsconfig changes may also be needed and must be coordinated as shared files. One agent should own the example plus those root dependency/check updates as a single change. This is independent of the core cancellation API and profile-semantics documentation.