# Development Guide (minesweeper-mcp)
このドキュメントは MCP server（stdio）を開発・テスト・公開するためのガイドです。
---
## 1. Design Constraints
### stdio の鉄則
- stdout は MCP protocol で使うため **ログを出さない**
- ログは stderr のみ
- 例外時も stack trace を stdout に流さない（stderr に寄せる）
### 設定は env を基本に
- `MINESWEEPER_BASE_URL`（必須）
- `MINESWEEPER_BEARER_TOKEN`（操作系に必須）
- 追加すると良い:
- `REQUEST_TIMEOUT_MS`（デフォルト 10000）
- `LOG_LEVEL`（デフォルト info）
---
## 2. Local Setup
```bash
npm install
npm run typecheck
npm run build
```
ローカル起動:
```bash
MINESWEEPER_BASE_URL="http://localhost:3000" \
MINESWEEPER_BEARER_TOKEN="xxxxx" \
node dist/index.js
```
---
## 3. Project Layout
```
.
├─ src/
│ ├─ index.ts # entry (stdio transport)
│ ├─ server.ts # MCP server + tool registration
│ ├─ tools/ # each tool implementation
│ ├─ rails/ # Rails API client
│ └─ config.ts # env / validation
├─ dist/ # build output
├─ docs/
├─ package.json
└─ tsconfig.json
```
---
## 4. 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」に変換。
---
## 5. 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 必須）
---
## 6. Coordinate / Board Expectations
- 0-index: x,y は 0..8
- boardは `board[y][x]`
- セル値は文字列:
- `#` / `F` / `0-8` / `X` / `M` / `!`
---
## 7. 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 になる
---
## 8. Inspector / Manual Verification
- MCP host を使わずに動作確認したい場合は Inspector を使う
- 目的:
- tools の一覧が正しい
- 入出力JSONが spec 通り
- stderr ログが汚染していない
チェック観点:
- stdout にログが混ざっていない（最重要）
- 401/422 で tool error が返る
---
## 9. Packaging (npx)
### package.json 必須設定
- `bin`:
- `"minesweeper-mcp": "dist/index.js"`
- `files`:
- `["dist"]`
- `type`: module / commonjs はプロジェクト方針で統一（SDKの導入に合わせる）
- `engines`:
- `"node": ">=18"`
### 公開前の確認
```bash
npm pack
tar -tf *.tgz | head
```
- distが含まれる
- binが正しく指している
- 起動して tools が出る
---
## 10. Security Notes
- token は絶対にログ出力しない（マスク）
- エラー body をそのまま吐く時も token は出さない
- Base URL のホストだけは表示OK（debug時）
---
## 11. 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` を増やす
