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):

{
       "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