D&D 知识导航器

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

什么是 MCP？

模型上下文协议 (MCP) 是 Anthropic 开发的一个框架，它使像 Claude 这样的 AI 助手能够与外部工具和服务进行通信。该服务器利用 Anthropic 的 Python 实现 FastMCP 协议，在 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”→“护甲等级”）
• 游戏特定符号的特殊术语识别（例如，“2d6+3”、“STR save”）
• 常见拼写错误的模糊匹配（例如，“firball”→“fireball”）
• 类别优先级排序，以将搜索重点放在相关内容上

要禁用查询增强，请在 enhance_query 函数中将参数设置为 False。

文档

全面的文档可在 docs/ 目录中找到：

• 使用指南：如何将 D&D 知识导航器与 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 开发模型上下文协议
• FastMCP 提供 MCP 的 Python 实现

包结构

D&D 知识导航器组织为一个 Python 包，其结构如下：

dnd-knowledge-navigator/
├── dnd_mcp_server.py      # 主服务器入口点
├── run_tests.py           # 运行所有测试的脚本
├── setup.py               # 包安装配置
├── src/                   # 源代码目录
│   ├── __init__.py        # 包初始化
│   ├── attribution/       # 来源归属系统
│   ├── core/              # 核心功能
│   ├── query_enhancement/ # 查询增强系统
│   └── templates/         # 响应格式模板
├── tests/                 # 测试目录
│   ├── __init__.py        # 测试包初始化
│   └── test_*.py          # 测试文件
└── docs/                  # 文档

有关包结构的更详细说明，请参阅包结构文档。

安装

要安装该软件包以进行开发：

# 克隆存储库
git clone https://github.com/yourusername/dnd-knowledge-navigator.git
cd dnd-knowledge-navigator

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 以开发模式安装软件包
pip install -e .

运行服务器

要启动 D&D 知识导航器服务器：

python dnd_mcp_server.py

运行测试

要运行所有测试：

./run_tests.py