# 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](docs/articles/dndmcp.md).

## 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](https://github.com/astral-sh/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):
     ```json
     {
       "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](docs/usage_guide.md): How to use the D&D Knowledge Navigator with Claude Desktop
- [Example Queries](docs/example_queries.md): Sample queries and expected responses
- [Troubleshooting Guide](docs/troubleshooting.md): Solutions for common issues
- [Source Attribution](docs/source_attribution.md): Details about the attribution system
- [Query Enhancement](docs/query_enhancement.md): Information about the query enhancement system
- [Blog Article](docs/articles/dndmcp.md): 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](https://www.dnd5eapi.co/) for providing the D&D data
- [Anthropic](https://www.anthropic.com/) for developing the Model Context Protocol
- [FastMCP](https://github.com/anthropics/anthropic-tools) 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](docs/package_structure.md).

### Installation

To install the package for development:

```bash
# 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:

```bash
python dnd_mcp_server.py
```

### Running Tests

To run all tests:

```bash
./run_tests.py
```