魂斗罗 MCP Demo

This project follows the architecture from Chris Nager's DOOM MCP App write-up, but uses an original placeholder browser game with Contra-style horizontal shooting.

The important part is not "MCP creates a game." The point is:

MCP can return a live app UI, not just text or JSON. In compatible clients, the game appears inside the conversation itself.

No original Contra assets, music, characters, levels, or ROM data are included.

Main Flow

• create_game_session: creates an inline game session and returns MCP App metadata so compatible hosts can render the game inline. It intentionally does not expose the browser fallback URL.
• get_game_launch_url: creates a signed /game/play?token=... URL for hosts that cannot render MCP Apps inline.
• /game/play?token=...: browser fallback route. The token is enough to boot the same game session without durable server-side session storage.
• ui://contra-style/mcp-app.html: the inline MCP App resource. It listens for the create_game_session tool result, extracts the session, and runs the game directly in the host iframe.

Optional extension tools:

• update-game-state: the MCP App can publish score, HP, position, enemies, ammo, and stage.
• get-game-state: reads the latest state.
• suggest-next-move: returns a Chinese gameplay suggestion from the latest state.

Run

npm install
npm run build
npm run serve

MCP endpoint:

http://localhost:3001/mcp

Use From Codex Or Another MCP Host

Ask the host to call:

create_game_session

If the host supports MCP Apps, it should render the game inline from:

ui://contra-style/mcp-app.html

That is the primary demo: the host calls a tool, and the tool result causes a playable game UI to appear in the chat surface. Do not show or open a fallback link in this path.

If inline rendering is unavailable, call:

get_game_launch_url

Then open the returned /game/play?token=... URL.

Browser Fallback

After npm run build && npm run serve, call get_game_launch_url and open the returned URL.

For quick UI development only:

npm run dev

That opens the game without a signed session, so it is useful for visual testing but not the main demo flow.

Controls

• Move: WASD or arrow keys
• Shoot: Space or J
• Restart: R

Video Talking Points

• This is modeled after the DOOM MCP App architecture, not a from-scratch game-dev tutorial.
• The headline is: MCP can return an interactive game UI inside the conversation.
• The primary path is inline-only; the signed browser launch URL is exposed only by get_game_launch_url.
• The MCP App runs the game directly in the host iframe; it does not iframe another page inside the app.
• The real MCP lesson: protocol + UI resource + signed launch flow can turn a web capability into an AI-client-native app.

Verification

npm run check
npm run build
curl -sS -X POST http://localhost:3001/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'