AI連携の道具とブリッジの設定
このページは、AI連携(MCP)とAI GMで使うブリッジ(axe-mcp.mjs)の起動のしかたと、AIが使える道具を1つずつ説明します。はじめて使う人は先にAI連携(MCP)のはじめての人の手順を読んでください。
ブリッジの2つの動かし方
ブリッジは1つのファイルで、起動のしかたで役目が変わります。
| 起動のしかた | 役目 | くわしい説明 |
|---|---|---|
node axe-mcp.mjs | AIのアプリ(Claude Code・Claude Desktopなど)からの頼みを、Axeのタブへ受け渡します | AI連携(MCP) |
node axe-mcp.mjs gm | ブリッジ自身がAIのAPIを呼び、AIをGMの席で動かします。初めはClaudeで、ほかのAIにも替えられます | AI GM |
1つ目の動かし方では、ふつうはAIのアプリがブリッジを起動します。自分で端末から起動する必要はありません。 2つ目の動かし方では自分で端末から起動します。
起動のときに足せる指定
指定は起動の行の後ろに空白で区切って足します。たとえば番号を変えるときは、node axe-mcp.mjs --port 47620と書きます。
| 指定 | 意味 | 初めの値 |
|---|---|---|
--port 番号 | Axeのタブがブリッジにつなぐ番号(ポート)。変えたら、Axeのパネルのブリッジの番号も同じ数にします | 47610 |
--allow-origin アドレス | 自分のサーバーに置いたAxeのページからも、タブを受け付けます。何度でも足せます | なし |
--http 番号 | AIのアプリとのやりとりを、標準の入出力の代わりにHTTPで受けます(下の節) | なし |
--max-usd 金額 | gmのときだけ。ブリッジが動いている間にAIが使える額の上限(米ドル)。何度始め直しても合わせて数えます | 20 |
--provider 名前 | gmのときだけ。claude(初めの値)かopenai(OpenAI互換のAPI)を選びます | claude |
--base-url アドレス | --provider openaiのときのAPIのアドレス | OpenAIのアドレス |
--model 名前 | --provider openaiのときに使うモデルの名前。何度でも足せます | なし |
--price 入力,出力 | --provider openaiのときのモデルの料金(100万トークンあたりの米ドル)。省くとトークン数で数えます | なし |
--max-tokens 数 | gmのときだけ。料金の分からないモデルが、ブリッジが動いている間に使えるトークン数の上限 | 2000000 |
--files-dir フォルダ | AIがファイルを読み書きしてよいフォルダ。画像の取り込みや部屋の保存は、このフォルダの中だけで行います | 起動した場所 |
--help | 使い方を英語で出して終わります | |
--version | ブリッジの版を出して終わります |
同じことを環境変数でも指定できます。環境変数はプログラムを起動するときに渡す名前つきの値です。
| 環境変数 | 意味 |
|---|---|
ANTHROPIC_API_KEY | gmのときに使うClaude APIのキー。ブリッジだけが持ち、Axeには送りません |
AXE_GM_API_KEY | gmを--provider openaiで動かすときのAPIのキー。キーの要らないサービスでは入れません |
AXE_GM_MAX_USD | --max-usdと同じです |
AXE_MCP_ALLOW_ORIGINS | --allow-originと同じです。アドレスが2つ以上あるときはカンマで区切ります |
AXE_MCP_TOKEN | --httpのときに、AIのアプリが示さなければならない合言葉(ベアラートークン) |
AXE_MCP_FILES_DIR | --files-dirと同じです |
つなげるページ
ブリッジは決まったページのAxeからのタブだけを受け付けます。知らないサイトが勝手にブリッジを使うのを防ぐためです。初めから受け付けるのは、公式の配信先(https://axe.xelltis.comなど)と、手元で開発するときのページ(http://localhost:4200など)です。
自分のサーバーに置いたAxeで使うときは、--allow-originにそのページのアドレスを足します。アドレスはhttps://example.comのように、https://から書きます。 Axeのパネルのつなぎ方には、開いているページに合わせて、この指定を足した形が出ます。
HTTPでつなぐ
Claude CodeとClaude Desktopは、ブリッジを自分で起動して、標準の入出力でやりとりします。この節の手順は要りません。 HTTPでつなぐのは、MCPのサーバーをアドレスで登録するAIのアプリを使うときです。
- 端末で
node axe-mcp.mjs --http 47611のように起動します。番号は空いているものを選びます。 - AIのアプリに、MCPのサーバーのアドレスとして
http://127.0.0.1:47611/mcpを登録します。 - Axeのパネルでつなぐを押します。
ブリッジが受け付けるのは、同じパソコンの中からのやりとりだけです。ほかのパソコンからはつなげません。同じパソコンのほかのプログラムからも使われたくないときは、環境変数AXE_MCP_TOKENに合言葉を入れて起動し、AIのアプリの側にも同じ合言葉をベアラートークンとして設定します。
安全のしくみ
- ブリッジは同じパソコンの中でだけ待ち受けます。インターネットの側からはつなげません。
- ブリッジにつなげるタブは1つです。2つ目のタブは断ります。
- AIが読めるのは、つないだ席の画面に出るものだけです。見えないコマ、開けないシート、読めない秘話は、AIにも渡しません。
- AIができるのは、つないだ席の役割でできることだけです。見学の席では読むだけになり、GMの道具はGMの席でだけ使えます。
- Axeのパネルで読むだけを選んでいる間は、書く道具をすべて断ります。
- AIが送った発言には、全員の画面でAIの印が付きます。AI連携をはじめたとき、終えたとき、許すことを変えたときは、全員向けの行が出ます。
- ブリッジとAxeの版が合わないときは、つなぐ前に互いに断ります。同じリリースの
axe-mcp.mjsを使います。 - ファイルを読み書きする道具は、
--files-dirのフォルダの中だけを使い、すでにあるファイルを上書きしません。部屋の読み込みは、席の画面で「はい」を押したときだけ行います。
道具の一覧
道具は、AIがAxeにできる操作の1つ1つです。頼むときに道具の名前を言う必要はありません。AIのアプリが「この道具を使ってよいか」と尋ねるときに、この名前が出ます。
コマやタブなどは名前かIDで指します。同じ名前のものが2つ以上あると、AIはどれかを選べずに断られるので、コマの名前は分けておくと確実です。マスは西の端から東へ1、2…、北の端から南へ1、2…と数えます。
読む道具
読むだけでも使えます。部屋を変えません。ただしsave_roomとsave_room_snapshotは、手元にファイルやスナップショットを残すので、書くことも許すときだけ使えます。
| 道具の名前 | すること |
|---|---|
get_room | 部屋の様子を見ます。席の名前と役割、テーブル、ラウンドと手番、チャットのタブ、ダイスボットが分かります |
list_pieces | 見ているテーブルのコマの一覧を読みます。位置・オーナー・リソース・バフ・ターゲットかどうかが分かります |
get_piece | コマを1つ、くわしく読みます。シート・バフ・チャットパレットが分かります |
get_turn_order | 行動順を読みます。並び、いまの手番、ラウンド、行動済みや待機のコマが分かります |
read_chat | チャットのタブの行を読みます。話した人、秘話の宛先、ダイスの結果、AIが送ったかどうかが分かります |
list_assets | 部屋にある物の一覧を、種類ごとに読みます。エフェクト・BGM・環境音・効果音・カットイン・画像・シーン・テーブル・射程・ダイスボットなどです |
read_scenario_text | シナリオテキストを、送る前に読みます。GMの席でだけ使えます |
wait_for_events | 部屋で何かが起きるのを待ち、起きたことを受け取ります(下の節) |
list_music | 流れている曲と、曲・プレイリストの一覧を読みます。曲のタグ・長さ・テンポも分かり、GMの席ではBGMを持つシーンも分かります |
list_room_snapshots | このブラウザが取っておいた部屋のスナップショットの一覧を読みます |
save_room | 部屋を保存ボタンと同じ形でzipに保存し、--files-dirのフォルダに書きます |
save_room_snapshot | 部屋のスナップショットを、このブラウザにいま取ります |
describe_kinds | 汎用の道具で扱える物の種類と、種類ごとの項目・書ける人・できる操作を読みます |
list_objects | ある種類の物の一覧を読みます |
get_object | 物を1つ読みます。その席に見せない中身は渡しません |
書く道具
書くことも許すのときに、見学でない席で使えます。
| 道具の名前 | すること |
|---|---|
send_chat | 発言します。席として、またはコマとして話せ、タブと秘話の宛先を選べます。チャットの特殊記法もそのまま効きます |
roll_dice | ダイスを振ります。シークレットダイスにもできます。ダイスボットが読めない式は、送る前に断ります |
move_piece | コマをマスへ動かします。高度も変えられます |
change_resource | コマのリソース(HPやMPなど)を増減するか、値を決めます。変更はチャットに残ります |
set_sheet_value | コマのシートの項目に値を書きます |
add_buff | コマにバフを付けます。続くラウンド数と、効果のメモを付けられます |
remove_buff | コマからバフを外します |
set_targets | この席のターゲットを選び直します。空にすると外します |
advance_turn | 行動順を進めます。次のコマへ、前のコマへ、指定のコマへ、次のラウンドへ、最初から、を選べます |
create_piece | 見ているテーブルに新しいコマを置きます。画像とシートの値を付けられます |
remove_piece | コマをテーブルから下げて、共有のインベントリに入れます |
fire_effect | エフェクトを全員に見せます。コマを狙うか、マスを狙います。撃ち手のコマも選べます |
play_sound | BGM・環境音・効果音を全員に鳴らします |
stop_sound | BGM・環境音を止めます。すべてを止めることもできます |
play_cut_in | カットインを全員に出します |
stop_cut_in | 出ているカットインを止めます |
switch_table | 全員の見ているテーブルを切り替えます。切り替え先のBGMとカットインも始まります |
place_range | 射程範囲を置きます。マスに置くか、コマに追従させます。立体にもできます |
remove_range | 射程範囲を消します |
play_music | BGMを流します。曲名かプレイリスト名で選ぶほか、「戦闘 緊迫」のような雰囲気の語で、名前やタグの合うものを選べます |
import_asset | --files-dirのフォルダにある画像・音・3Dモデルを、落としたときと同じ上限で部屋に取り込みます |
import_character | キャラクターシートを、取り込みのパネルと同じく、アドレスか貼り付けたJSONから取り込みます |
load_room | 保存した部屋かスナップショットを、今の部屋の代わりに読み込みます。席の画面で確かめ、1分で答えがなければやめます |
create_object | ある種類の物を作ります |
change_object | 物の項目を書き換えます。書ける人は種類と項目ごとに画面と同じです |
remove_object | 物を消します |
act_on_object | カードを裏返す、ダイスを振るなど、項目を書くだけではできない操作をします |
GMだけが使えるエフェクトは、GMの席からだけ撃てます。コマとして話せるのは、その席がシートを開けるコマだけです。change_resourceとset_sheet_valueも、シートを開けるコマにだけ効きます。バフを隠したコマのバフは、GMの席からだけ付け外しできます。秘話の宛先には席の名前を書きます。コマの名前を書くと、そのコマのオーナーの席への秘話になります。
GMの道具
GMの席で、書くことも許すのときだけ使えます。
| 道具の名前 | すること |
|---|---|
generate_map | マップの生成パネルと同じく、ダンジョンか野外のマップを新しいテーブルに作ります |
apply_scene | シーンを適用します。テーブル・見た目・音・カットイン・時計・開幕の文が切り替わります |
send_scenario_text | シナリオテキストを、書いてあるとおりにチャットへ送ります |
AI GMの道具
パネルのGMを任せるのタブからAIのアプリにGMをさせるときに、AIが使います。ブリッジが答える道具で、gmを付けずに起動したときだけ並びます。
| 道具の名前 | すること |
|---|---|
wait_for_turn | AI GMとしての次の番を待ちます。番が来ると、理由・起きたこと・指示・メモを受け取ります |
update_notes | AIのメモを書き直します。書いたメモはパネルのGMを任せるのタブに出ます |
起きたことを待つ
AIは頼まれたときにだけ動きます。プレイヤーの発言に続けて応えさせるには、AIに「待つ」ことをさせます。wait_for_eventsはそのための道具です。
この道具を呼ぶと、AIは部屋で何かが起きるまで待ち、起きたことをまとめて受け取ります。受け取るのは、チャットの行(ダイスの結果を含みます)、手番とラウンドの変化、コマの出入りと移動、テーブルの切り替え、席の出入りです。何も起きなければ、決めた秒数で戻ります。AIは続けて待ち直すので、前に受け取った所の続きから読めます。
GMを任せるときの進め方(部屋を読む、待つ、応える、また待つ)は、次の節の手引きに入っています。
AIに渡す手引き
ブリッジは道具のほかに、AI向けの手引きを3つ持っています。
| 手引き | 中身 |
|---|---|
axe://guide/run-session | GMとしてセッションを進めるときの進め方 |
axe://guide/run-ai-gm | パネルのGMを任せるのタブから動かされるGMとしての進め方 |
axe://guide/chat-syntax | ダイス・リソース・バフ・手番・エフェクト・カットインの記法 |
Claude Codeでは/mcp__axe__run_sessionと打つと、GMとして進める手引きをAIに渡せます。/mcp__axe__run_ai_gmと打つと、GMを任せるのタブから動かされるGMの手引きを渡せます。プロンプトを選べないアプリでは、AIに「axe://guide/run-sessionを読んでGMをして」と頼みます。
AIが断られたときの答え
道具が断られると、AIには理由の種類と英語の説明が返ります。AIがその内容を伝えてきたときの見方です。
| 理由の種類 | 意味 | 直しかた |
|---|---|---|
not_connected | ブリッジにAxeのタブがつながっていません | Axeのパネルでつなぐを押します |
not_allowed | その席や、いまのAIに許すことでは、できない操作です | 書くことも許すに切り替えるか、役割を確かめます |
not_found | 名前の合うコマやタブなどが見つかりません | 名前を確かめます。別のテーブルにあるコマは見つかりません |
ambiguous | 同じ名前のものが2つ以上あり、どれか選べません | 名前を分けるか、AIにIDで指すように頼みます |
invalid_input | 頼みの中身が道具の決まりに合いません | AIが直して呼び直します。続くときは、頼み方を具体的にします |
unknown_tool | その名前の道具がありません | ブリッジとAxeを同じリリースにそろえます |
failed | 操作を試みましたが、できませんでした | 返ってきた説明を読みます |
timeout | 時間内に終わりませんでした | もう一度頼みます。続くときは、Axeのタブが開いたままかを確かめます |