Submarine Attack Mcp Ui

English / Japanese

Currently, much of the UI and data is written in Japanese.
Since prompts are more stable when written in the author's native language, we have decided that Japanese is best at this stage as development is still ongoing.
Please wait a while for the English translation.
Most of the readme.md is machine translated.

The game rules are similar to the grid attack from Nintendo's Wi-Fi-enabled World's Anyone Plays Encyclopedia (3x1 attacks are not included yet).

Game Rule

The rules and board control of the submarine game are handled by MCP. The user plays as player 1 and the AI plays as player 2.

Available MCP clients

There are no general MCP clients that guarantee asymmetric data presentation, where the information presented by the MCP to the user and the LLM is different (the user can see the user's board but not the LLM's board, and the LLM can see the LLM's board but not the user's board), and currently only Avatar-Shell meets this condition (to a limited extent).

• Avatar-Shell

Note: This MCP Server outputs HTML data using the ui:// schema for each move. If the MCP client function uses LLM to read the ui: tag, the AI may use a large amount of tokens.
When you first start using it, please check for unexpected token consumption.
Although commercial AI APIs are smarter, if you can use a local LLM, we recommend trying it with openai/gpt-oss-20b or higher, which has the tool function.

Get started

Public Server

Submarine attack MCP-UI is built on the MCPAgent mechanism of CloudFlare AI Agent and supports Streamable-http connections.

A demo using Cloudflare workers is available below.

Please configure the following MCP settings on each MCP client.

{
  "mcpServers": {
    "submarine": {
      "type": "streamable-http",
      "url": "https://submarine-attack-mcp-ui.daisycodes.workers.dev/mcp"
    }
  }
}

After successfully connecting the Submarine MCP and loading the rule resource, you can run it by clicking "Play the Submarine Game".
Depending on the performance of the LLM, it may not work reliably or additional instructions may be required via chat. Instructions such as "User will instruct Black to take the move. Assistant will execute White's move" may also be required.

(The public server may be shut down in the future.)

Local Server

You can run it as a local server by running wrangler locally.

pnpm run dev # run wrangler local

or 

npm run dev # run wrangler local

Please configure the following MCP settings on each MCP client. The name of the MCP should be something like "submarine" or "game" so that LLM can identify it as a submarine game.

{
  "mcpServers": {
    "submarine": {
      "type": "streamable-http",
      "url": "http://localhost:8787/mcp"
    }
  }
}

Note: Starting wrangler seems to result in an error within a Docker container.

How to Play

1. After connecting submarine-attack-mcp as an MCP server, first load the GameRule resource file, which describes the game rules, into LLM.
2. Enter a command to start the game, such as "Let's start the submarine game."
3. The MCP server will be called. By default, Avatar-Shell will ask the user whether they wish to operate the MCP; select Accept. To skip the prompt, set the permissions for each tool in the Avatar settings to "Always Allow."
4. Once the MCP server is running, the initial board state will be displayed. Select the pieces you want to use from the piece buttons at the top, then click on your board to place them all. If you don't want to bother, press the "Random Placement" button to place them all randomly. Once you've placed them, press the "Confirm this placement" button.
5. The LLM will query the MCP server and place the pieces at its discretion. After placement, the game turn will begin. Click on your opponent's board to attack. If the LLM has placed a piece, it will turn red. If they have not placed a piece, it will be framed white. (The current version does not include effects such as explosions.) After waiting a few seconds, the LLM will attack the board (a red or white frame will appear on the left side of the screen). These attacks will be repeated alternately. You win when all of your opponent's pieces are red.

Note: Depending on the performance of your LLM, it may not be able to issue the correct command and may end up repeatedly calling the MCP server. Also, the LLM may get the order of operations wrong. If something goes wrong, you can "converse in chat and directly tell the AI, 'It's your turn next." Enjoy the fact that, since you're playing against an AI, you can progress through the game through dialogue.

Tool Functions and UI Actions

tool functions

• new-game
  Initializes the game and waits for the user and AI to set up the initial board.
• get-board
  Get the current game board state. Show the user a graphical html representation of the game state from player 1's perspective, and send the AI a text-based representation of the game state from player 2's perspective.
  • text state for AI

  const board = {
      type:"text", 
      text:"--------\n" +
      "SubmarineGameState\n" +
      "phase: placementP1\n" +
      "current_player: 1\n" +
      "\n" +
      "[PLAYER 1 PERSPECTIVE]\n" +
      "\n" +
      "SELF_BOARD_TRUE (7x7, y=0..6 top to bottom, x=0..6 left to right)\n" +
      "legend: '.'=empty, 'S'=ship, 'X'=hit ship, 'o'=miss\n" +
      "row0: .......\n" +
      "row1: .......\n" +
      "row2: .......\n" +
      "row3: .......\n" +
      "row4: .......\n" +
      "row5: .......\n" +
      "row6: .......\n" +
      "\n" +
      "OPPONENT_BOARD_KNOWLEDGE (7x7, y=0..6 top to bottom, x=0..6 left to right)\n" +
      "legend: '.'=unknown, 'X'=hit, 'o'=miss\n" +
      "row0: .......\n" +
      "row1: .......\n" +
      "row2: .......\n" +
      "row3: .......\n" +
      "row4: .......\n" +
      "row5: .......\n" +
      "row6: .......\n" +
      "\n" +
      "total_shots_fired_by_self: 0\n" +
      "total_hits_on_opponent: 0"
  }
  

• player1-placement
  Sets the placement of pieces for Player 1 (user side). This assumes that the JavaScript on the board will generate JSON directly from the user's placement instructions and call the MCP.
  Because the schema is not public (any type), the AI cannot call it in the correct format, and the AI cannot interfere with the user's board.
• player2-placement
  Sets the placement of pieces for Player 2 (AI side). It is assumed that the AI will call and set this according to the json format information provided by MCP when new-game is started.
• player1-attacked
  The board JavaScript reports the attack position of player 1 (user side) to the MCP. This assumes that the board javascript will generate it directly from the user's placement instructions and call the MCP.
  Because the schema is not public (any type), the LLM side cannot call it in the correct format, and the AI cannot interfere with the user's board.
• player2-attack-position
  Specifies the attack position for Player 2 (AI). It is assumed that the AI will specify the attack position as the game progresses.

The html screen generated by MCP-UI cannot be obtained by LLM because Avatar-Shell strictly adheres to { annotations: { audience: ["user"], }}.
This means that LLM cannot know the current state of Player 1 (the user).
Currently, for debugging purposes, for Avatar-Shell, the state of Player 2 (the AI side) can be seen by setting "all" on the conversation screen. We are considering whether to strictly block this from being shown to the user, but we do not think that this is necessary at the moment.

UI Actions

Currently, the submarine game MCP-UI can issue the following UI actions from the user board.

• tool player1-placement
  The piece position information set when piece placement is completed immediately after the game is transmitted to the MCP.
• tool player1-attacked
  Information on the user's attack on player 2's board. This is evaluated using JavaScript on the html page, and the results are received and confirmed on the MCP side.

resource

• file:///game-rule
  These are the rules of the submarine game that will be presented to the AI. For the sake of efficiency, they are currently written in Japanese, the author's native language.
  src/rule/gameRule.ts

Program Structure

Submarine attack rules are processed within the MCP Server. This means that the AI cannot directly intervene in the execution of the rules. This prevents the AI from cheating according to the rules, which is a common occurrence with AI.
In addition, Avatar-Shell strictly processes the audience so that the AI does not know the user's board state.

Note
In the MCP specifications, audience is information for reference only, and there are no specifications that MCP clients must strictly adhere to. Therefore, the game may not function properly on other MCP clients.
These issues are affected by the MCP specifications, MCP-UI specifications, and MCP client specifications, so it is unclear whether they will be resolved in the future.

Rule Logic

The main rule processing is done in src/rule/logic.ts, and the board processing is done in src/rule/client.ts (some rule processing is done in src/client_embed.ts).

Board generation

The board drawing process uses the tsx in src/components and src/rule/client.ts (converted to embedded js and embedded in the string src/client_embed.ts).
It displays the board information according to the information from the MCP side and processes simple motions in response to user clicks.

MCP handling

MCP and MCP-UI processing is done in src/index.tsx. It is almost identical to the Cloudflare MCPAgent sample code.

Local Debugging and Deployment

This mostly follows the instructions for running and debugging Cloudflare MCPAgent.

pnpm install # install

pnpm run dev # start dev server

pnpm run inspector # start inspector

pnpm run deploy # deploy to cloudflare workers

Guide (Japanese)

Notes

The previous Reversi game was simple, but this one was a bit of a mess with the overall structure and forced me to incorporate TSX, making it quite confusing.
It might have been easier to understand if I'd simply built it using only JS and HTML.

To build the program, we manually modified the source code generated by ChatGPT5 to 5.2.