Dnd MCP

D&D知识导航器

一个基于Python的服务器，实现了模型上下文协议（MCP），将克劳德和其他人工智能助手连接到龙与地下城5e游戏信息。

什么是MCP？

模型上下文协议（MCP）是由Anthropic开发的一个框架，它使像Claude这样的人工智能助手能够与外部工具和服务进行通信。该服务器利用Anthropic的Python协议实现FastMCP，在人工智能助手和D&D 5e API之间创建结构化桥梁。

有关MCP的详细说明以及该项目如何实现它，请查看我们的 博客文章.

特性

• FastMCP集成：为AI助手提供查询D&D游戏数据的工具和资源
• D&D 5e API集成：完全访问法术、怪物、装备、职业、种族等
• 高效缓存：持久本地存储API响应以提高性能
• 结构化数据访问：用于一致人工智能交互的明确资源和工具
• 消息来源：全面跟踪和显示信息来源
• 视觉格式：用于展示D&D内容的Markdown模板
• 查询增强：通过同义词处理和模糊匹配对D&D查询进行智能处理

设置

先决条件

• Python 3.10或更高版本
• 紫外线 包管理器（推荐）
• Claude桌面客户端（用于与Claude一起使用）

安装

1. 克隆此存储库：

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

1. 安装依赖项：

   uv pip install -r requirements.txt

或

   pip install .

1. 配置Claude桌面（如果与Claude一起使用）：

- 创建一个 claude_desktop_config.json Claude Desktop配置目录中的文件 - 添加以下配置（根据需要调整路径）：

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

1. 运行服务器：

   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内容的模板系统：

• 具有有序属性和能力的怪物属性块
• 带有格式化组件和效果的拼写描述
• 具有组织属性的设备详细信息
• 可配置的格式选项（表格、表情符号、压缩模式）

要禁用模板，请设置 TEMPLATES_ENABLED = False 在……里面 src/templates/config.py.

查询增强系统

该服务器包括一个查询增强系统，可以改善搜索结果：

• D&D术语的同义词处理（例如“AC”→ “装甲等级”）
• 游戏特定符号的特殊术语识别（例如“2d6+3”、“STR保存”）
• 常见拼写错误的模糊匹配（例如“firball”）→ “火球”）
• 分类优先级，将搜索重点放在相关内容上

要禁用查询增强，请在中设置参数 enhance_query 功能到 False.

文档

综合文档可在 docs/ 目录：

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

缓存资源

服务器在 cache/ 目录，以最大限度地减少API调用并提高响应时间。此目录通过以下方式从git中排除 .gitignore.

配置

编辑 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许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

• 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