LoreKeeper MCP

A Model Context Protocol (MCP) server for D&D 5e information lookup with AI assistants. LoreKeeper provides fast, cached access to comprehensive Dungeons & Dragons 5th Edition data through the Open5e and D&D 5e APIs.

Features

Comprehensive D&D 5e Data: Access spells, monsters, classes, races, equipment, and rules
Intelligent Caching: SQLite-based caching with TTL support for fast responses
Dual API Support: Primary Open5e API with D&D 5e API fallback for complete coverage
Type-Safe Configuration: Pydantic-based configuration management
Modern Python Stack: Built with Python 3.13+, async/await patterns, and FastMCP
Production Ready: Comprehensive test suite, code quality tools, and pre-commit hooks

Quick Start

Prerequisites

Python 3.13 or higher
uv for package management

Installation

# Clone the repository git clone https://github.com/your-org/lorekeeper-mcp.git cd lorekeeper-mcp # Install dependencies uv sync # Set up pre-commit hooks uv run pre-commit install # Copy environment configuration cp .env.example .env

Running the Server

# Start the MCP server (recommended) lorekeeper serve # Or with custom configuration lorekeeper -v serve lorekeeper --db-path /custom/path.db serve # Backward compatible: start server without CLI uv run python -m lorekeeper_mcp

Available Tools

LoreKeeper provides 5 MCP tools for querying D&D 5e game data:

lookup_spell - Search spells by name, level, school, class, and properties
lookup_creature - Find monsters by name, CR, type, and size
lookup_character_option - Get classes, races, backgrounds, and feats
lookup_equipment - Search weapons, armor, and magic items
lookup_rule - Look up game rules, conditions, and reference information

See docs/tools.md for detailed usage and examples.

Document Filtering

All lookup tools and the search tool support filtering by source document:

# List available documents first documents = await list_documents() # Filter spells to SRD only srd_spells = await lookup_spell( level=3, documents=["srd-5e"] ) # Filter creatures from multiple sources creatures = await lookup_creature( type="dragon", documents=["srd-5e", "tce", "phb"] ) # Search with document filter results = await search_dnd_content( query="fireball", documents=["srd-5e"] )

This allows you to:

Limit searches to SRD (free) content only
Filter by specific published books or supplements
Separate homebrew from official content
Control which sources you're using for licensing reasons

See docs/document-filtering.md for comprehensive guide and cross-source filtering examples.

CLI Usage

LoreKeeper includes a command-line interface for importing D&D content:

# Import content from OrcBrew file lorekeeper import MegaPak_-_WotC_Books.orcbrew # Show help lorekeeper --help lorekeeper import --help

See docs/cli-usage.md for detailed CLI documentation.

Configuration

LoreKeeper uses environment variables for configuration. Create a .env file:

# Database settings DB_PATH=./data/cache.db CACHE_TTL_DAYS=7 ERROR_CACHE_TTL_SECONDS=300 # Logging LOG_LEVEL=INFO DEBUG=false # API endpoints OPEN5E_BASE_URL=https://api.open5e.com DND5E_BASE_URL=https://www.dnd5eapi.co/api

Development

Project Structure

lorekeeper-mcp/ ├── src/lorekeeper_mcp/ # Main package │ ├── cache/ # Database caching layer │ │ └── db.py # SQLite cache implementation │ ├── api_clients/ # External API clients │ ├── tools/ # MCP tool implementations │ ├── config.py # Configuration management │ ├── server.py # FastMCP server setup │ └── __main__.py # Package entry point ├── tests/ # Test suite │ ├── test_cache/ # Cache layer tests │ ├── test_config.py # Configuration tests │ ├── test_server.py # Server tests │ └── conftest.py # Pytest fixtures ├── docs/ # Documentation ├── pyproject.toml # Project configuration ├── .pre-commit-config.yaml # Code quality hooks └── README.md # This file

Running Tests

# Run all tests uv run pytest # Run with coverage uv run pytest --cov=lorekeeper_mcp # Run specific test file uv run pytest tests/test_cache/test_db.py

Code Quality

The project uses several code quality tools:

Black: Code formatting (100 character line length)
Ruff: Linting and import sorting
MyPy: Static type checking
Pre-commit: Git hooks for automated checks

# Run all quality checks uv run ruff check src/ uv run ruff format src/ uv run mypy src/ # Run pre-commit hooks manually uv run pre-commit run --all-files

Database Cache

LoreKeeper uses SQLite with WAL mode for efficient caching:

Schema: api_cache table with indexes on expiration and content type
TTL Support: Configurable cache duration (default: 7 days)
Content Types: Spells, monsters, equipment, etc. for organized storage
Source Tracking: Records which API provided cached data
Automatic Cleanup: Expired entries are automatically pruned

API Strategy

The project follows a strategic API assignment:

Prefer Open5e API over D&D 5e API
Prefer Open5e v2 over v1 when available
Use D&D 5e API only for content not available in Open5e (primarily rules)
Each category maps to ONE API to avoid complexity

See docs/tools.md for detailed API mapping and implementation notes.

📋 OpenSpec Integration

This project uses OpenSpec as its core development tooling for specification management and change tracking. OpenSpec provides:

Structured Specifications: All features, APIs, and architectural changes are documented in detailed specs
Change Management: Comprehensive change tracking with proposals, designs, and implementation tasks
Living Documentation: Specifications evolve alongside the codebase, ensuring documentation stays current
Development Workflow: Integration between specs, implementation, and testing

The openspec/ directory contains:

Current specifications for all project components
Historical change records with full context
Design documents and implementation plans
Task breakdowns for development work

When contributing, please review relevant specifications in openspec/ and follow the established change management process.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and ensure tests pass
Run code quality checks: uv run pre-commit run --all-files
Commit your changes
Push to your fork and create a pull request

Testing

All contributions must include tests:

New features should have corresponding unit tests
Maintain test coverage above 90%
Use pytest fixtures for consistent test setup
Follow async/await patterns for async code

License

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

Acknowledgments

Open5e for comprehensive D&D 5e API
D&D 5e API for official rules reference
FastMCP for the MCP server framework

LoreKeeper MCP

LoreKeeper MCP

Features

Quick Start

Prerequisites

Installation

Running the Server

Available Tools

Document Filtering

CLI Usage

Configuration

Development

Project Structure

Running Tests

Code Quality

Database Cache

API Strategy

📋 OpenSpec Integration

Contributing

Development Workflow

Testing

License

Acknowledgments

Resources

New MCP Servers

Latest Blog Posts

MCP directory API