# monban guide

monban MCP は Guide First 方針で使います。最初に `guide` tool を読み、以後の作業全体の context として扱ってください。

## MCP 導入後の基本

- local MCP server は、作業フォルダで `npm install @monban-online/cli@latest` を実行し、`./node_modules/.bin/monban mcp` を起動する導線を標準にします。
- `npx --yes @monban-online/cli@latest mcp` は補助導線です。npm cache 競合で `ENOTEMPTY` になることがあるため、sandbox 検証や本番導入では local install 済み bin を優先してください。
- グローバル共有 CLI や `npm --prefix` で monban MCP を起動する場合は、利用側プロジェクトを `monban mcp --workspace-root /path/to/project` または `MONBAN_WORKSPACE_ROOT=/path/to/project` で明示してください。
- monban の利用には Google OAuth ログインが必要です。
- 認証情報や設定状態は MCP 登録ファイルではなく monban のローカル状態に保存します。
- 生の認証トークンを表示しないでください。
- `get_login_status` が `authenticated: false` または `LOGIN_REQUIRED` を返す場合は、`login` tool を実行し、ブラウザ認証を完了してから `get_current_plan`、`get_openrouter_status`、`apply_counter` を再実行してください。
- plan の確認には `get_current_plan` tool を使います。
- OpenRouter OAuth 接続状態の確認には `get_openrouter_status` tool を使います。
- `get_openrouter_status` が未接続を返す場合は、`connect_openrouter` tool を実行し、ブラウザで OpenRouter の接続を完了してから `get_openrouter_status` を再実行してください。
- OpenRouter のモデル候補確認には `list_openrouter_models` tool を使います。
- 窓口の `settings.yaml` には `model` を1件だけ明示してください。自動選択や未指定 default には依存しません。
- 初期値の `model: openrouter/free` は、OpenRouter の無料モデル router として使う明示 model slug です。
- Free plan では monban 側のモデル fallback を提供しません。

## 窓口作成

- 新規窓口作成では空入力で `create_counter` tool を使います。
- `create_counter` は prefix なしの16文字 lowercase alphanumeric counterId を自動生成し、ローカル作業フォルダに同名フォルダと初期ファイルを作成します。設置者や AIエージェントが URL 用 ID を指定しません。
- `create_counter`、`validate_counter`、`apply_counter`、`sync_inquiries` の結果に含まれる `workspaceRoot` を確認し、利用側プロジェクトではなく CLI 提供元リポジトリを指している場合は MCP 起動設定を直してください。
- 作成されるファイルは `settings.yaml`、`SYSTEM_PROMPT.md` です。`settings.yaml.counterId` は生成済み ID の記録であり、編集対象にしません。
- `settings.yaml` の `model` は設置者と確認して決めます。実 OpenRouter API の検証では、ユーザの明示承認がない限り無料モデルまたは無料モデル router を指定してください。
- `settings.yaml` の `initialMessage` は monban 窓口ページで最初に表示される定型の吹き出しであり、CTA iframe の背景で繰り返しストリーミング表示する文でもあります。どんなことを相談できる窓口か、どんな入力をするとよいかを書いてください。
- 設置者サイトには、monban 提供の CTA iframe `/cta/:counterId` を埋め込めます。CTA のテーマカラーは counter files ではなく iframe URL の `themeColor` query で指定します。設置者がこの CTA デザインを使わない場合は、自作の CTA から monban 窓口ページ `/c/:counterId` へ通常リンクします。
- 公開ページへ出す準備ができた窓口は、`settings.yaml` の `status` を `published` にしてから `validate_counter` と `apply_counter` を実行してください。作成直後の初期値は `draft` です。停止する場合は `stopped` を使います。
- `apply_counter` は既定ではローカル反映ログを作成しません。反映結果は tool の返却値で確認してください。デバッグ用途で反映ログが必要な場合だけ、MCP 起動時に `--write-apply-record` または `MONBAN_WRITE_APPLY_RECORD=true` を指定します。
- 作成される2ファイル以外に、応答本文や分岐を管理する追加ファイルを作らないでください。
- 初期ファイルを読み、設置者とやり取りしながら窓口内容を詰めてください。
- server 反映前の検証には `validate_counter` tool を使います。
- 問い合わせ履歴は `sync_inquiries` tool で同期し、`<counterId>/inquiries/latest.json` に保存されます。このファイルには問い合わせ本文や訪問者 Gmail アドレス snapshot が含まれる可能性があります。

## 制限中の通常 MCP

Global Ban 中または一時制限中の通常 MCP では、`login`、`get_login_status`、`get_global_ban_status`、`submit_global_ban_appeal`、`get_global_ban_appeal_status` の5つだけを使えます。`guide` tool も許可 tool には含まれません。

## 作らない tool

`doctor` tool は作りません。状態確認は目的ごとの特化型 tool を使います。