Foundryvtt MCP

🚀 FoundryVTT MCP Server

FoundryVTTと統合されたModel Context Protocol (MCP)サーバーです。AIアシスタントがテーブルトップゲームのセッションとやり取りできるようになります。自然言語でアクターを検索したり、ダイスを振ったり、コンテンツを生成したり、ゲームワールドを管理したりできます。

🚀 クイックスタート

このセクションでは、FoundryVTT MCP Serverの基本的な使い方や初期設定について説明します。

✨ 主な機能

コア機能

• 🎲 ダイスロール - 標準的なRPG表記でダイスを振ることができます。
• 🔍 データクエリ - アクター、アイテム、シーン、ジャーナルエントリを検索できます。
• 📊 ゲーム状態 - 現在のシーン、戦闘状態、ワールド情報にアクセスできます。
• 🎭 コンテンツ生成 - NPC、戦利品、ランダムエンカウンターを生成できます。
• 📝 ルール検索 - ゲームルールやメカニカルな情報を照会できます。

リアルタイム統合

• 🔄 ライブ更新 - WebSocket接続により、リアルタイムのゲーム状態を取得できます。
• ⚔️ 戦闘管理 - イニシアチブと戦闘状態を追跡できます。
• 👥 ユーザー認識 - 誰がオンラインで、そのステータスを確認できます。

AI機能

• 🧠 戦術提案 - 戦闘アドバイスや戦略的なヒントを得ることができます。
• 🎪 ストーリー支援 - プロットのヒントや物語要素を生成できます。
• 🎨 ワールドビルディング - 場所、NPC、クエストをオンデマンドで作成できます。

📦 インストール

前提条件

• Node.js 18+
• FoundryVTTサーバーが実行中で、アクセス可能であること
• MCP互換のAIクライアント（Claude Desktopなど）

クイックセットアップ（推奨）

🧙‍♂️ インタラクティブなセットアップウィザード:

git clone <repository-url>
cd foundry-mcp-server
npm install
npm run setup-wizard

セットアップウィザードは以下のことを行います。

• FoundryVTTサーバーを自動検出します。
• 接続性と認証をテストします。
• .env構成ファイルを生成します。
• セットアップ全体を検証します。

手動セットアップ

1. クローンとインストール:

git clone <repository-url>
cd foundry-mcp-server
npm install

2. 環境構成:

cp .env.example .env
# .envをFoundryVTTの詳細で編集します。

3. 必要な環境変数:

FOUNDRY_URL=http://localhost:30000
FOUNDRY_API_KEY=your_api_key_here
# またはユーザー名/パスワードを使用:
FOUNDRY_USERNAME=your_username
FOUNDRY_PASSWORD=your_password

4. テストと起動:

npm run test-connection  # セットアップを検証します。
npm run build
npm start

開発モード

npm run dev

💻 使用例

基本的な使用法

AIアシスタントに以下のようなことを尋ねることができます。

ダイスロール:

• "攻撃ロールで1d20+5を振って"
• "能力値用に4d6で最低値を落として振って"
• "ダメージ用に2d10+3を振って"

ゲームデータ:

• "このシーンのすべてのNPCを表示して"
• "パーティのインベントリ内の魔法武器を探して"
• "現在の戦闘のイニシアチブ順はどうなっているか"
• "回復薬を検索して"

コンテンツ生成:

• "ランダムなNPC商人を生成して"
• "CR 5のエンカウンター用の戦利品を作成して"
• "NPCとプロットのヒントがある宿を生成して"

高度な使用法

ルール検索:

• "絞め技のルールを調べて"
• "ファイアボールの呪文はどういう仕組みか"
• "恐怖状態になる条件は何か"

戦術アドバイス:

• "ドラゴンと戦うための戦術を提案して"
• "今ターン、魔法使いは何をすべきか"
• "この戦闘エンカウンターを分析して"

ワールドビルディング:

• "神秘的な森の場所を作成して"
• "行方不明な商人を巻き込んだサイドクエストを生成して"
• "レベル8のキャラクターに適した魔法アイテムを設計して"

利用可能なツール

データアクセス

• search_actors - キャラクター、NPC、モンスターを検索します。
• search_items - 装備、呪文、消耗品を検索します。
• search_journals - ノートと配布資料を検索します。
• get_scene_info - 現在のシーンの詳細を取得します。
• get_actor_details - 詳細なキャラクター情報を取得します。

ゲームメカニクス

• roll_dice - 任意の式でダイスを振ります。
• update_actor_hp - キャラクターのHPを変更します。
• get_combat_status - 戦闘状態とイニシアチブを取得します。
• lookup_rule - ゲームルールと呪文の説明を照会します。

コンテンツ生成

• generate_npc - ランダムなNPCを作成します。
• generate_loot - レベルに適した戦利品を作成します。
• roll_table - ランダムなエンカウンター、イベント、天候を生成します。
• suggest_tactics - 戦闘アドバイスと戦略を提案します。

診断とシステムヘルス

• get_system_health - サーバーのパフォーマンスとヘルスメトリックを取得します。
• get_recent_logs - フィルタリングされたFoundryVTTのログを取得します。
• search_logs - 正規表現パターンでログを検索します。
• diagnose_errors - トラブルシューティングの提案を伴うエラー分析を行います。

利用可能なリソース

サーバーは以下のFoundryVTTリソースを公開しています。

• foundry://world/info - ワールドとキャンペーンの情報
• foundry://world/actors - ワールド内のすべてのアクター
• foundry://scene/current - 現在のアクティブなシーン
• foundry://combat/current - アクティブな戦闘状態
• foundry://compendium/spells - 呪文データベース
• foundry://compendium/monsters - モンスターデータベース

設定

サーバー設定

.envを編集してカスタマイズできます。

# ロギング
LOG_LEVEL=info  # debug, info, warn, error

# パフォーマンス
FOUNDRY_TIMEOUT=10000      # リクエストのタイムアウト（ms）
FOUNDRY_RETRY_ATTEMPTS=3   # 失敗したリクエストを再試行する回数
CACHE_TTL_SECONDS=300      # データを5分間キャッシュする

セキュリティ

• 可能な場合はパスワードの代わりにAPIキーを使用してください。
• FoundryVTTユーザーの権限を必要最小限に制限してください。
• サーバーを内部ネットワークでのみ実行してください。
• 不審な活動についてログを監視してください。

診断とトラブルシューティング

組み込み診断

サーバーには、接続とパフォーマンスの問題をトラブルシューティングするための包括的な診断ツールが含まれています。

接続テスト:

# 完全なMCP接続と機能をテストします。
npm run test-connection

# クリーンビルドとセットアップをテストします。
npm run setup

診断ツール（AIアシスタント経由）:

• システムヘルス: "FoundryVTTシステムのヘルスステータスを取得して"
• エラー分析: "最近のエラーを診断し、推奨事項を提供して"
• ログ検索: "過去1時間のログで'connection'パターンを検索して"
• 最近の問題: "最近のエラーログを表示して"

高度な診断

Local REST APIモジュールを使用すると、高度な診断機能にアクセスできます。

• 🔍 リアルタイムログ分析 - FoundryVTTのコンソール出力と通知を監視します。
• 📊 システムヘルスメトリック - サーバーのパフォーマンス、メモリ使用量、クライアント接続を監視します。
• 🎯 エラーパターン認識 - 一般的な問題を自動検出します。
• 💡 スマート提案 - コンテキストに応じたトラブルシューティングの推奨事項を提供します。
• 📈 パフォーマンス監視 - サーバーの稼働時間と応答時間を追跡します。

接続問題

# FoundryVTT接続をテストします。
curl http://localhost:30000/api/status

# サーバーログを確認します。
npm run dev  # 詳細なログを表示します。

一般的な問題

"Failed to connect to FoundryVTT"

• FOUNDRY_URLが正しいことを確認してください。
• FoundryVTTが実行中であることを確認してください。
• APIアクセスが有効になっていることを確認してください。

"Authentication failed"

• APIキーまたはユーザー名/パスワードを確認してください。
• FoundryVTTでのユーザー権限を確認してください。
• ユーザーが禁止/制限されていないことを確認してください。

"Tool not found" errors

• サーバーの最新バージョンに更新してください。
• ツール名のスペルを確認してください。
• ログ内の利用可能なツールを確認してください。

開発

プロジェクト構造

src/
├── config/           # 構成管理
├── foundry/          # FoundryVTTクライアントと型定義
├── tools/            # MCPツールの定義
├── resources/        # MCPリソースの定義
├── utils/            # ユーティリティとロギング
└── index.ts          # メインサーバーのエントリポイント

新しいツールの追加

1. src/tools/index.tsでツールスキーマを定義します。
2. src/index.tsにハンドラーメソッドを追加します。
3. src/foundry/client.tsでFoundryVTT API呼び出しを実装します。
4. src/foundry/types.tsにTypeScriptの型を追加します。
5. AIアシスタントでテストします。

テスト

# テストを実行します。
npm test

# カバレッジを含めて実行します。
npm run test:coverage

# コードをリントします。
npm run lint

ビルド

# 開発用ビルド
npm run build

# クリーンビルド
npm run clean && npm run build

APIリファレンス

環境変数

⭐ APIキーまたはユーザー名/パスワードのどちらかが必要です。

ツールスキーマ

roll_dice

{
  "formula": "1d20+5",
  "reason": "Attack roll against goblin"
}

search_actors

{
  "query": "goblin",
  "type": "npc",
  "limit": 10
}

generate_npc

{
  "race": "human",
  "level": 5,
  "role": "merchant",
  "alignment": "neutral good"
}

統合例

Claude Desktopの設定

Claude DesktopのMCP設定に以下を追加します。

{
  "mcpServers": {
    "foundry": {
      "command": "node",
      "args": ["/path/to/foundry-mcp-server/dist/index.js"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_API_KEY": "your_api_key_here"
      }
    }
  }
}

カスタムMCPクライアント

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["./dist/index.js"],
});

const client = new Client(
  {
    name: "foundry-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  },
);

await client.connect(transport);

// ダイスを振る
const result = await client.request({
  method: "tools/call",
  params: {
    name: "roll_dice",
    arguments: {
      formula: "1d20+5",
      reason: "Initiative roll",
    },
  },
});

ロードマップ

バージョン0.2.0

• [ ] 戦闘管理ツール（戦闘の開始/終了、イニシアチブの進行）
• [ ] トークン操作（移動、ステータスエフェクトの更新）
• [ ] シーンのナビゲーションと切り替え
• [ ] プレイリストの制御と環境音

バージョン0.3.0

• [ ] キャラクターシートの編集（レベルアップ、装備の追加）
• [ ] ジャーナルエントリの作成と編集
• [ ] マクロの実行と管理
• [ ] 高度なコンテンツ生成（ダンジョン、完全なステータスを持つNPC）

バージョン1.0.0

• [ ] マルチワールドサポート
• [ ] ユーザー権限管理
• [ ] 外部トリガー用のWebhookサポート
• [ ] パフォーマンスの最適化とキャッシュ
• [ ] 完全なテストカバレッジ
• [ ] Dockerデプロイメント

ドキュメント

完全なAPIドキュメントはdocs/ディレクトリにあり、TypeScriptソースコードとJSDocコメントから自動生成されています。

📖 ドキュメントの閲覧

ローカル開発:

npm run docs        # ドキュメントを生成します。
npm run docs:serve  # 生成してローカルでサーブします。

オンライン: このリポジトリのdocs/フォルダを参照するか、GitHub Pagesサイト（有効になっている場合）を訪問してください。

📚 ドキュメントの内容

• FoundryClient API - 例付きの完全なクライアントドキュメント
• TypeScriptインターフェース - すべてのデータ構造と型定義
• 設定 - 環境変数とセットアップオプション
• ユーティリティ - ヘルパー関数とロギング
• 使用例 - 一般的な操作のコードサンプル

ソースコードが変更されると、ドキュメントはGitHub Actionsを介して自動更新されます。

コントリビュート

1. リポジトリをフォークします。
2. 機能ブランチを作成します: git checkout -b feature/amazing-feature
3. 変更を加え、テストを追加します。
4. コミットします: git commit -m 'Add amazing feature'
5. プッシュします: git push origin feature/amazing-feature
6. プルリクエストを開きます。

コードスタイル

• TypeScriptのstrictモードを使用してください。
• 既存の命名規則に従ってください。
• 公開APIにJSDocコメントを追加してください。
• 新しい機能に対してテストを書いてください。
• 意味のあるコミットメッセージを使用してください。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

トラブルシューティング

🔍 クイック診断

npm run test-connection      # FoundryVTTの接続性をテストします。
npm run setup-wizard        # インタラクティブなセットアップを再実行します。

🏥 ヘルスチェック

get_health_status MCPツールを使用して包括的な診断を行うか、起動時のサーバーログを確認して詳細なステータス情報を取得してください。

📚 一般的な問題

• 接続拒否：設定されたポートでFoundryVTTが実行されていることを確認してください。
• 認証失敗：.env内のAPIキーまたはユーザー名/パスワードを確認してください。
• 検索結果が空："Foundry Local REST API"モジュールをインストールして有効にしてください。
• 機能制限：完全な機能を利用するにはREST APIモジュールが必要です。

📖 詳細なトラブルシューティングガイド: TROUBLESHOOTING.md

サポート

• 問題報告: GitHub Issuesでバグや機能要求を報告してください。
• Discord: FoundryVTT Discord #api-development
• ドキュメント: FoundryVTT API Docs
• トラブルシューティング: TROUBLESHOOTING.md

謝辞

• 素晴らしいVTTプラットフォームを提供してくれたFoundryVTTチーム
• Model Context Protocolを提供してくれたAnthropic
• インスピレーションとフィードバックを提供してくれたテーブルトップゲーミングコミュニティ

楽しいゲームプレイを！ 🎲