D&D Knowledge Navigator

D&D 知识导航器

这是一个基于 Python 的服务器，实现了模型上下文协议（MCP），可将 Claude 和其他 AI 助手连接到《龙与地下城》5e 游戏信息。

什么是 MCP？

模型上下文协议（MCP）是 Anthropic 开发的框架，可让 Claude 等 AI 助手与外部工具和服务通信。本服务器使用 FastMCP（Anthropic 对该协议的 Python 实现），在 AI 助手与 D&D 5e API 之间搭建结构化桥梁。

如需详细了解 MCP 以及本项目如何实现该协议，请参阅我们的博客文章。

功能

• FastMCP 集成：为 AI 助手提供用于查询 D&D 游戏数据的工具和资源
• D&D 5e API 集成：完整访问法术、怪物、装备、职业、种族等信息
• 高效缓存：在本地持久化存储 API 响应，以提升性能
• 结构化数据访问：提供定义清晰的资源和工具，确保 AI 交互一致
• 来源归属：全面追踪并展示信息来源
• 视觉化排版：使用 Markdown 模板精美呈现 D&D 内容
• 查询增强：通过同义词处理和模糊匹配，智能处理 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/ 目录中：

• 使用指南：介绍如何将 D&D Knowledge Navigator 与 Claude Desktop 搭配使用
• 查询示例：示例查询及预期响应
• 故障排除指南：常见问题的解决方案
• 来源归属：归属系统的详细信息
• 查询增强：查询增强系统的相关信息
• 博客文章：详细介绍 MCP 及此实现

缓存资源

服务会在 cache/ 目录中维护本地缓存，以尽量减少 API 调用并提高响应速度。此目录通过 .gitignore 从 git 中排除。

配置

编辑 prompts.py 可修改或添加新的提示词模板；编辑 resources.py 可调整资源端点。

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 D&D 5e API 提供 D&D 数据
• 感谢 Anthropic 开发 Model Context Protocol
• 感谢 FastMCP 提供 MCP 的 Python 实现

软件包结构

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