AI导哈

D&D游戏数据服务

一个基于Python的服务，通过Model Context Protocol（MCP）连接AI助手与D&D 5e游戏数据及自定义角色和战役信息。

  • by Josh-Gotro
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Josh-Gotro/dnd-mcp

使用说明

D&D核心规则和角色信息

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

特性

  • FastMCP集成：为AI助手提供查询D&D游戏数据的工具和资源
  • D&D 5e API集成：完全访问法术、怪物、装备、职业、种族等
  • 小型Supabase集成：从轻量级数据库中访问角色和特定战役的信息。
  • 高效缓存：持久本地存储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

  2. 安装依赖项：

    uv pip install -r requirements.txt

    或

    pip install .

  3. 配置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"
      ]
    }
  }
}

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

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

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

查询增强系统

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

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

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

文档

综合文档可在 docs/ 目录：

缓存资源

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

配置

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

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

封装结构

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

相关 MCP