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

Clone this repository:

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

Install dependencies:

uv pip install -r requirements.txt

pip install .

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"
      ]
    }
  }
}

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.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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