D&D Knowledge Navigator

D&D ナレッジナビゲーター

Claude やその他の AI アシスタントを Dungeons & Dragons 5e のゲーム情報に接続する、Model Context Protocol（MCP）を実装した Python ベースのサーバーです。

MCP とは？

Model Context Protocol（MCP）は、Claude のような AI アシスタントが外部のツールやサービスと通信できるようにするため、Anthropic が開発したフレームワークです。このサーバーは、Anthropic によるプロトコルの Python 実装である FastMCP を活用し、AI アシスタントと D&D 5e API をつなぐ、構造化されたブリッジを作成します。

MCP の詳しい説明と、このプロジェクトでの実装方法については、ブログ記事をご覧ください。

機能

• FastMCP 統合：D&D のゲームデータを照会するためのツールとリソースを AI アシスタントに提供します
• D&D 5e API 統合：呪文、モンスター、装備、クラス、種族などに完全にアクセスできます
• 効率的なキャッシュ：API レスポンスをローカルに永続保存し、パフォーマンスを向上させます
• 構造化データアクセス：一貫性のある AI とのやり取りを実現する、明確に定義されたリソースとツールを提供します
• 情報源の明記：情報源を包括的に追跡し、表示します
• 視覚的な書式設定：D&D コンテンツを美しく表示する Markdown テンプレートを提供します
• クエリの強化：同義語の処理やあいまい検索を用いて、D&D に関するクエリをインテリジェントに処理します

セットアップ

前提条件

• Python 3.10 以降
• uv パッケージマネージャー（推奨）
• Claude Desktop クライアント（Claude で使用する場合）

インストール

1. このリポジトリをクローンします。

   git clone https://github.com/yourusername/dnd-knowledge-navigator.git
   cd dnd-knowledge-navigator
   

2. 依存関係をインストールします。

   uv pip install -r requirements.txt
   

   または

   pip install .
   

3. Claude Desktop を設定します（Claude で使用する場合）。

   • Claude Desktop の設定ディレクトリに claude_desktop_config.json ファイルを作成します
   • 次の設定を追加します（必要に応じてパスを調整してください）。

     {
       "mcpServers": {
         "dnd": {
           "command": "/path/to/uv",
           "args": [
             "--directory",
             "/path/to/dnd-knowledge-navigator",
             "run",
             "dnd_mcp_server.py"
           ]
         }
       }
     }
     

4. サーバーを実行します。

   uv run python dnd_mcp_server.py
   

MCP ツールの使用

AI アシスタントに接続すると、次のツールを使用できます。

• search_all_categories：すべての D&D リソースを対象に、指定した語句を検索します
• verify_with_api：公式 API のデータと照合して、D&D に関する記述を検証します
• check_api_health：D&D 5e API の稼働状況とステータスを確認します

情報源の明記システム

このサーバーには、次の機能を備えた包括的な情報源の明記システムが含まれています。

• ユーザーに返されるすべての情報について、情報源を追跡します
• 各情報に信頼度を付与します
• API エンドポイントと関連度スコアを含めます
• 情報源を明確に提示できるよう、情報源の詳細を書式設定します

テンプレートシステム

このサーバーには、D&D コンテンツを書式設定するテンプレートシステムが含まれています。

• 属性と能力を整理して表示する、モンスターのステータスブロック
• 構成要素と効果を書式設定した、呪文の説明
• 特性を整理して表示する、装備の詳細
• 書式設定オプション（表、絵文字、コンパクトモード）の設定

テンプレートを無効にするには、src/templates/config.py で TEMPLATES_ENABLED = False を設定します。

クエリ強化システム

このサーバーには、検索結果を改善するクエリ強化システムが含まれています。

• D&D 用語の同義語を処理します（例：「AC」→「armor class」）
• ゲーム固有の表記を認識します（例：「2d6+3」、「STR save」）
• よくあるスペルミスをあいまい検索で処理します（例：「firball」→「fireball」）
• 関連性の高いコンテンツに検索対象を絞るため、カテゴリに優先順位を付けます

クエリ強化を無効にするには、enhance_query 関数のパラメーターを False に設定します。

ドキュメント

包括的なドキュメントは、docs/ ディレクトリにあります。

• 使い方ガイド：Claude Desktop で D&D Knowledge Navigator を使用する方法
• クエリの例：クエリのサンプルと期待される応答
• トラブルシューティングガイド：一般的な問題の解決方法
• ソースの帰属：帰属システムの詳細
• クエリの拡張：クエリ拡張システムに関する情報
• ブログ記事：MCP とこの実装についての詳しい説明

キャッシュされたリソース

サーバーは、API 呼び出しを最小限に抑え、応答時間を短縮するために、cache/ ディレクトリにローカルキャッシュを保持します。このディレクトリは .gitignore により Git の対象から除外されています。

設定

プロンプトテンプレートを変更または追加するには prompts.py を編集し、リソースのエンドポイントを調整するには resources.py を編集してください。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

謝辞

• D&D データを提供している D&D 5e API に感謝します
• Model Context Protocol を開発した Anthropic に感謝します
• MCP の Python 実装を提供する FastMCP に感謝します

パッケージ構成

D&D Knowledge Navigator は、次の構成の Python パッケージとして整理されています。

dnd-knowledge-navigator/
├── dnd_mcp_server.py      # Main server entry point
├── run_tests.py           # Script to run all tests
├── setup.py               # Package installation configuration
├── src/                   # Source code directory
│   ├── __init__.py        # Package initialization
│   ├── attribution/       # Source attribution system
│   ├── core/              # Core functionality
│   ├── query_enhancement/ # Query enhancement system
│   └── templates/         # Response formatting templates
├── tests/                 # Test directory
│   ├── __init__.py        # Test package initialization
│   └── test_*.py          # Test files
└── docs/                  # Documentation

パッケージ構成の詳細については、パッケージ構成のドキュメントをご覧ください。

インストール

開発用にパッケージをインストールするには：

# Clone the repository
git clone https://github.com/yourusername/dnd-knowledge-navigator.git
cd dnd-knowledge-navigator

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package in development mode
pip install -e .

サーバーの起動

D&D Knowledge Navigator サーバーを起動するには：

python dnd_mcp_server.py

テストの実行

すべてのテストを実行するには：

./run_tests.py