D&D 知识导航器

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

什么是 MCP？

模型上下文协议 (MCP) 是由 Anthropic 开发的一个框架，它使像 Claude 这样的 AI 助手能够与外部工具和服务进行通信。该服务器利用 FastMCP（Anthropic 的 MCP 协议的 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 文件
   • 添加以下配置（根据需要调整路径）：
     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 保存”）
• 常见拼写错误的模糊匹配（例如，“firball” → “fireball”）
• 类别优先级，以专注于相关内容

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

文档

详细的文档可以在 docs/ 目录中找到：

• 使用指南：如何使用 Claude Desktop 与 D&D 知识导航器
• 示例查询：示例查询及其预期响应
• 故障排除指南：常见问题的解决方案
• 来源归属：关于归属系统的详细信息
• 查询增强：关于查询增强系统的详细信息- 博客文章: 详细解释了MCP及其实现

缓存资源

服务器在cache/目录中维护本地缓存，以最小化API调用并提高响应时间。此目录通过.gitignore被排除在git之外。

配置

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

贡献

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

1. 叉分仓库
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      # 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知识导航器服务器：

python dnd_mcp_server.py

运行测试

要运行所有测试：

./run_tests.py