minesweeper-mcp (stdio)

Rails 8 で動く Minesweeper Web/API を操作するための stdio MCP server です。
Claude Code / Claude Desktop などの MCP Host からツールとして呼び出して使います。

• 起動: npx minesweeper-mcp（公開後）

• 通信: stdio（stdout は MCP プロトコル専用 / ログは stderr のみ）

• 操作: Rails の REST API に対して start/open/flag/chord/end を呼ぶ

API: https://github.com/geeknees/minesweeper-for-ai

Quick Start

1) 必要要件

• Node.js 22+（推奨: 24+）

• Rails 側の Web/API が起動していること

2) 環境変数

最低限これを設定します。

• MINESWEEPER_BASE_URL (必須)
  例: https://example.com（末尾スラッシュなし推奨）

• MINESWEEPER_BEARER_TOKEN（操作系に必須）
  Rails 側で発行した token（1回しか表示されない想定）

例:

3) ローカル起動（開発中）

MCPの設定方法（Host側）

MCP Host（Claude Desktop / Claude Code など）の設定ファイルに、stdioサーバとして登録します。 ローカルで動かす場合は dist/index.js を指定し、環境変数を渡してください。

ローカル開発（distを直接起動）

公開後（npxで起動）

設定ファイルの場所や再読み込み方法は、使用しているMCP Hostのドキュメントに従ってください。

MCP Tools

ツール名は「Rails APIの意図が分かる」ように分けています。

user_start

ユーザーに紐づく token を使って、新しい game を開始します（開始のたびに新しい public_id が発行される）。

Input:

Output:

game_state

公開ゲームの state を取得します（token不要）。

Input:

Output:

game_open

Input:

game_flag（トグル）

Input:

game_chord

Input:

game_end

Input:

（任意）user_games

公開の games 一覧取得（token不要）。

Input:

Output:

Error Handling

Rails 側は { "error": "message" } を返します。 MCP server はそれを tool error に変換します。

• 401: Unauthorized (missing/invalid token)

• 404: Not found

• 422: Unprocessable (invalid state/coords/etc)

• その他: Request failed (status=...)

Logging

• stdout: MCP プロトコル専用（ログ出力禁止）

• stderr: ログ出力OK

環境変数 LOG_LEVEL（例: debug|info|warn|error）をサポートするのを推奨。

Project Layout

License

TBD

ローカル起動:

3. Tool Implementation Pattern

推奨構造

• tool関数は「入力の軽い検証 → Rails client呼び出し → 成功/失敗の整形」に徹する

• Rails client は「URL組み立て/headers/timeout/JSON parse」を担う

例:

• src/tools/game_open.ts が rails.postOpen(publicId, x, y) を呼ぶ

• src/rails/client.ts が fetch を担当

例外設計（推奨）

• RailsHttpError（status, message, rawBody）

• ConfigError（env不足）

• ValidationError（入力値の形式不正）

tool側はそれを捕まえて「tool error」に変換。

4. Rails API Mapping

ベースURL: ${MINESWEEPER_BASE_URL}

• start: POST /users/:slug/start （Authorization 必須）

• state: GET /games/:public_id/state（公開）

• open: POST /games/:public_id/open（Authorization 必須）

• flag: POST /games/:public_id/flag（Authorization 必須）

• chord: POST /games/:public_id/chord（Authorization 必須）

• end: POST /games/:public_id/end（Authorization 必須）

5. Coordinate / Board Expectations

• 0-index: x,y は 0..8

• boardは board[y][x]

• セル値は文字列:

  • # / F / 0-8 / X / M / !

6. Testing Strategy

Unit tests（軽量）

• env validation のテスト

• Rails client の URL 組み立て

• エラー変換（401/422/404など）

Integration tests（推奨）

• Rails を起動して実際に叩く（CIでは docker compose が便利）

• 重点:

  • tokenなし操作が401になる

  • stateは公開で取れる

  • open/flag/chord の 422 ケースが tool error になる

7. Inspector / Manual Verification

• MCP host を使わずに動作確認したい場合は Inspector を使う

• 目的:

  • tools の一覧が正しい

  • 入出力JSONが spec 通り

  • stderr ログが汚染していない

チェック観点:

• stdout にログが混ざっていない（最重要）

• 401/422 で tool error が返る

8. Packaging (npx)

package.json 必須設定

• bin:

  • "minesweeper-mcp": "dist/index.js"

• files:

  • ["dist"]

• type: module / commonjs はプロジェクト方針で統一（SDKの導入に合わせる）

• engines:

  • "node": ">=18"

公開前の確認

• distが含まれる

• binが正しく指している

• 起動して tools が出る

9. Security Notes

• token は絶対にログ出力しない（マスク）

• エラー body をそのまま吐く時も token は出さない

• Base URL のホストだけは表示OK（debug時）

10. Troubleshooting

1) “MCP tools not found”

• bin が登録されていない / distが入ってない

• package.json bin と files を確認

2) “protocol parse error”

• stdout にログが混ざっている

• console.log を禁止し、loggerを stderr に

3) “401 Unauthorized”

• MINESWEEPER_BEARER_TOKEN が未設定か誤り

• Rails 側で token を再発行できない仕様なので、正しい token を使う必要がある

4) “Fetch failed / timeout”

• MINESWEEPER_BASE_URL が間違っている

• Rails が落ちている

• REQUEST_TIMEOUT_MS を増やす