Fantasy Tabletop Helper

ファンタジー卓上ゲームヘルパー — MCP サーバー

Claude Desktop、Cursor、Codex、または任意の MCP 対応クライアントを卓上ゲームのキャンペーンに接続し、自分の世界について自然な言葉で質問できます。

「ウェストルーンで宗教に属している NPC は誰で、そのうちパーティーがすでに会ったことがあるのは誰ですか？」

このリポジトリには、接続に関するドキュメントとクライアント設定の例が含まれています。サーバー自体はホストされており、fantasytabletophelper.com 内で実行されるため、インストール、クローン、起動したままにしておく作業は必要ありません。

• エンドポイント： https://www.fantasytabletophelper.com/api/mcp — www. を付けてください。詳しくは以下を参照してください
• トランスポート： ステートレスな Streamable HTTP、POST のみ
• アクセス： Hero プラン + PAT（ftth_mcp_…）。読み取りと、制限付きの書き込み（提案／自分が作成したメモ／イベント）が可能です。OAuth ではありません。これは別の課題です。
• ソース： 非公開です。アプリは商用製品であり、このリポジトリにはクライアント側の部分が含まれています。

---

あなたに限定（読み取り + 制限付きの書き込み）

サーバーは管理者としてではなく、あなたとしてデータベースにクエリを実行します。行レベルセキュリティによって回答が決まるため、ログイン中にウェブサイトで表示される内容しか見ることはできません。

書き込み機能もありますが、対象は限定されています。あなたが作成したメモとイベント、あなたが送信した振り返り、そして DM が確認するための提案です。この接続を通じて AI ツールが行った内容は、DM がアプリで確認するまでキャンペーンの正史にはなりません。

	閲覧できる人
パーティー用メモ	キャンペーンのメンバー
DM 専用メモ	そのキャンペーンの DM、または作成者
プライベートメモ	作成者のみ
コーデックスの項目	そのキャンペーンのメンバー。正史に含まれない項目は DM のみ

あなたがプレイヤーの場合、AI クライアントをキャンペーンに接続しても DM の秘密が表示されることはありません。これはアプリケーションコードではなく、データベースによって強制されています。

ツール

ツール	返される内容
list_campaigns	あなたのキャンペーンと、それぞれでのあなたの役割
get_campaign	1 つのキャンペーンの詳細
list_sessions	セッション。最近プレイしたものから順に表示
search_codex	NPC、場所、アイテム、伝承、宗教、文化、グループ
get_subject	1 つのコーデックス項目の全情報と、その関連項目
get_session_notes	1 つのセッションのメモ
get_session_recap	セッションの振り返り。DM の場合は DM 用の準備フックも含む
append_session_note	メモを追加（公開範囲の指定が必要）
submit_session_recap	自分が書いた振り返りを保存
propose_subject	DM が確認するためのコーデックス項目を提案
propose_relationship	既存の 2 つの項目間の関連を提案
list_session_events	閲覧可能なロールと戦闘イベント
append_session_event	種類を指定したイベントを 1 件追加（ロール／命中／回復など）
get_session_transcript	最新の利用可能な文字起こし。DM 専用で、音声は含まれません

陣営とギルドは kind: "group" として保存されます。独立した faction の種類はありません。

---

セットアップ

1. トークンを作成する

サイトで Account → AI Tool Access（/account/mcp）に移動し、接続するツールの名前をトークンに付けて、Create token を押します。

トークンは一度だけ表示され、ftth_mcp_ で始まります。表示されたときにコピーしてください。 保存されるのはハッシュのみなので、後から再表示することはできません。紛失した場合は、トークンを失効させて新しいものを作成してください。

2. クライアントを設定する

すぐに編集できるファイルは examples/ にあります。たとえば Claude Desktop の場合：

{
  "mcpServers": {
    "ftthelper": {
      "url": "https://www.fantasytabletophelper.com/api/mcp",
      "headers": { "Authorization": "Bearer ftth_mcp_YOUR_TOKEN_HERE" }
    }
  }
}

クライアントを再起動してください。ツール一覧に ftthelper が表示されます。

www. を付ける

これは見た目だけの問題ではありません。www なしのドメインは www にリダイレクトされます。HTTP クライアントは、リダイレクトによってオリジンが変わると Authorization ヘッダーを削除します。移動先のホストに認証情報を渡してよいか判断できないためで、これは妥当な動作です。クライアントに https://fantasytabletophelper.com/api/mcp を指定すると、通信中にトークンが削除されます。そのためサーバーには匿名のリクエストが届き、有効なトークンでも 401 Invalid or missing MCP token が返されます。

3. 質問する

「自分のキャンペーンを一覧表示してから、ウェストルーンのキャンペーンにある宗教をすべて探してください。」

---

トークンの失効

Account → AI Tool Access で、トークンの横にある Revoke を押してください。次回、そのクライアントからリクエストがあったときに反映されます。自分で管理できなくなった場所に貼り付けたトークンは、失効させてください。

トラブルシューティング

症状	原因
404	パスが間違っているか、このデプロイではサーバーが無効になっています。
401 作成したばかりのトークンで発生する場合	ほとんどの場合、URLが原因です。トークンが削除されてしまうため、www. のないドメインではなく、URLを確認してください。トークンを疑う前に確認しましょう。
401	トークンが間違っているか、失効しているか、有効期限が切れています。新しいトークンを作成してください。
503	お客様のアカウントのセッションを開始できませんでした。通常は一時的な問題です。再試行してください。
403	プランがHeroではありません。
429	ソフトレート制限を超えています（トークンごとに約60リクエスト／分）。Retry-After を待ってください。
GETで 405 が発生する	想定どおりです。サーバーはPOSTのみ対応しています。クライアントではPOSTを使用してください。
接続はできるが、すべてのツール呼び出しでエラーが返る	サーバー側の設定に問題があります。サーバーのログに記録されるため、サポートにお問い合わせください。
ツールが空のリストを返す	通常はそのとおりです。キャンペーンがまだないか、検索結果が見つかりませんでした。

最後の2つの行は分けて考える必要があります。空のリストは回答ですが、エラーは障害です。

ライセンス

ドキュメントと設定例：MIT。ホストされたサービスには、独自の利用規約があります。