D&D Knowledge Navigator

D&D Knowledge Navigator

A Python-based server implementing the Model Context Protocol (MCP) that connects Claude and other AI assistants to Dungeons & Dragons 5e game information.

What is MCP?

The Model Context Protocol (MCP) is a framework developed by Anthropic that enables AI assistants like Claude to communicate with external tools and services. This server leverages FastMCP, Anthropic's Python implementation of the protocol, to create a structured bridge between AI assistants and the D&D 5e API.

For a detailed explanation of MCP and how this project implements it, check out our blog article.

Features

• FastMCP Integration: Provides AI assistants with tools and resources to query D&D game data
• D&D 5e API Integration: Complete access to spells, monsters, equipment, classes, races, and more
• Efficient Caching: Persistent local storage of API responses for improved performance
• Structured Data Access: Well-defined resources and tools for consistent AI interactions
• Source Attribution: Comprehensive tracking and display of information sources
• Visual Formatting: Markdown templates for beautiful presentation of D&D content
• Query Enhancement: Intelligent processing of D&D queries with synonym handling and fuzzy matching

Setup

Prerequisites

• Python 3.10 or higher
• uv package manager (recommended)
• Claude Desktop client (for using with Claude)

Installation

1. Clone this repository:

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

2. Install dependencies:

   uv pip install -r requirements.txt
   

   or

   pip install .
   

3. Configure Claude Desktop (if using with Claude):

   • Create a claude_desktop_config.json file in your Claude Desktop configuration directory
   • Add the following configuration (adjust paths as needed):

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

4. Run the server:

   uv run python dnd_mcp_server.py
   

MCP Tool Usage

When connected to an AI assistant, the following tools are available:

• search_all_categories: Search across all D&D resources for specific terms
• verify_with_api: Verify D&D statements against official API data
• check_api_health: Check the health and status of the D&D 5e API

Source Attribution System

The server includes a comprehensive source attribution system that:

• Tracks the source of all information returned to the user
• Provides confidence levels for each piece of information
• Includes API endpoints and relevance scores
• Formats attribution information for clear presentation

Template System

The server includes a template system for formatting D&D content:

• Monster stat blocks with organized attributes and abilities
• Spell descriptions with formatted components and effects
• Equipment details with organized properties
• Configurable formatting options (tables, emojis, compact mode)

To disable templates, set TEMPLATES_ENABLED = False in src/templates/config.py.

Query Enhancement System

The server includes a query enhancement system that improves search results:

• Synonym handling for D&D terminology (e.g., "AC" → "armor class")
• Special term recognition for game-specific notation (e.g., "2d6+3", "STR save")
• Fuzzy matching for common misspellings (e.g., "firball" → "fireball")
• Category prioritization to focus searches on relevant content

To disable query enhancement, set parameters in the enhance_query function to False.

Documentation

Comprehensive documentation is available in the docs/ directory:

• Usage Guide: How to use the D&D Knowledge Navigator with Claude Desktop
• Example Queries: Sample queries and expected responses
• Troubleshooting Guide: Solutions for common issues
• Source Attribution: Details about the attribution system
• Query Enhancement: Information about the query enhancement system
• Blog Article: Detailed explanation of MCP and this implementation

Cached Resources

The server maintains a local cache in the cache/ directory to minimize API calls and improve response time. This directory is excluded from git via .gitignore.

Configuration

Edit prompts.py to modify or add new prompt templates, or resources.py to adjust resource endpoints.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• D&D 5e API for providing the D&D data
• Anthropic for developing the Model Context Protocol
• FastMCP for the Python implementation of MCP

Package Structure

The D&D Knowledge Navigator is organized as a Python package with the following structure:

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

For a more detailed explanation of the package structure, see Package Structure Documentation.

Installation

To install the package for development:

# 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 .

Running the Server

To start the D&D Knowledge Navigator server:

python dnd_mcp_server.py

Running Tests

To run all tests:

./run_tests.py