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
or
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 termsverify_with_api: Verify D&D statements against official API datacheck_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:
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
