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 API.

Features

• Comprehensive D&D 5e Data: Access spells, monsters, classes, races, equipment, and rules
• Semantic Search: Milvus Lite vector database with natural language search capabilities
• Open5e API Integration: Access to comprehensive D&D 5e content via Open5e API
• Type-Safe Configuration: Pydantic-based configuration management
• Modern Python Stack: Built with Python 3.11+, async/await patterns, and FastMCP
• Production Ready: Comprehensive test suite, code quality tools, and pre-commit hooks

Quick Start

Prerequisites

• Python 3.11 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 6 MCP tools for querying D&D 5e game data:

1. search_spell - Search spells by name, level, school, class, and properties
2. search_creature - Find monsters by name, CR, type, and size
3. search_character_option - Get classes, races, backgrounds, and feats
4. search_equipment - Search weapons, armor, and magic items
5. search_rule - Look up game rules, conditions, and reference information
6. search_all - Unified search across all content types with semantic search

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 search_spell(
    level=3,
    documents=["srd-5e"]
)

# Filter creatures from multiple sources
creatures = await search_creature(
    type="dragon",
    documents=["srd-5e", "tce", "phb"]
)

# Search with document filter
results = await search_all(
    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. All settings use the LOREKEEPER_ prefix. Create a .env file:

# Cache backend settings
LOREKEEPER_CACHE_BACKEND=milvus        # "milvus" (default) or "sqlite"
LOREKEEPER_MILVUS_DB_PATH=~/.local/share/lorekeeper/milvus.db  # or $XDG_DATA_HOME/lorekeeper/milvus.db
LOREKEEPER_EMBEDDING_MODEL=all-MiniLM-L6-v2

# SQLite settings (if using sqlite backend)
LOREKEEPER_DB_PATH=./data/cache.db

# Cache TTL settings
LOREKEEPER_CACHE_TTL_DAYS=7
LOREKEEPER_ERROR_CACHE_TTL_SECONDS=300

# Logging
LOREKEEPER_LOG_LEVEL=INFO
LOREKEEPER_DEBUG=false

# API endpoints
LOREKEEPER_OPEN5E_BASE_URL=https://api.open5e.com

Semantic Search

LoreKeeper uses Milvus Lite as the default cache backend, providing semantic search capabilities powered by vector embeddings.

Features

• Semantic Search: Find content by meaning, not just exact text matches
• Vector Embeddings: Uses sentence-transformers for high-quality text embeddings
• Hybrid Search: Combine semantic queries with structured filters
• Zero Configuration: Works out of the box with sensible defaults
• Lightweight: Embedded database, no external services required

Usage Examples

# Find spells by concept (not just keywords)
healing = await search_spell(search="restore health and cure wounds")
# Returns: Cure Wounds, Healing Word, Mass Cure Wounds, etc.

# Find creatures by behavior
flyers = await search_creature(search="flying creatures with ranged attacks")
# Returns: Dragon, Wyvern, Harpy, etc.

# Hybrid search: semantic + structured filters
fire_evocation = await search_spell(
    search="area fire damage",
    level=3,
    school="evocation"
)
# Returns: Fireball (exact match for both semantic and filter)

# Search across all content types
results = await search_all(query="dragon breath weapon")

First-Run Setup

On first run, LoreKeeper downloads the embedding model (~80MB). This is a one-time download:

# First run will show:
# Downloading model 'all-MiniLM-L6-v2'...
lorekeeper serve

Configuration

Configure Milvus via environment variables:

# Use Milvus backend (default)
LOREKEEPER_CACHE_BACKEND=milvus

# Custom database path (defaults to $XDG_DATA_HOME/lorekeeper/milvus.db)
LOREKEEPER_MILVUS_DB_PATH=/path/to/milvus.db

# Alternative embedding model
LOREKEEPER_EMBEDDING_MODEL=all-MiniLM-L6-v2

Migrating from SQLite

If you were using an older version with SQLite caching:

1. Set the backend to Milvus (default):

   LOREKEEPER_CACHE_BACKEND=milvus

2. Re-import your data (Milvus cache starts empty):

   lorekeeper import /path/to/content.orcbrew

3. Or let it repopulate from APIs on first query.

Rollback: To keep using SQLite (no semantic search):

LOREKEEPER_CACHE_BACKEND=sqlite
LOREKEEPER_DB_PATH=./data/cache.db

Note: SQLite cache does not support semantic search—only exact and pattern matching.

Development

Project Structure

lorekeeper-mcp/
├── src/lorekeeper_mcp/          # Main package
│   ├── cache/                   # Vector database caching layer
│   │   ├── milvus.py           # Milvus Lite cache implementation
│   │   ├── embedding.py        # Embedding service for semantic search
│   │   ├── protocol.py         # Cache protocol definition
│   │   └── factory.py          # Cache factory
│   ├── api_clients/            # External API clients
│   ├── repositories/           # Repository pattern for data access
│   ├── 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

Vector Database Cache

LoreKeeper uses Milvus Lite for semantic search and efficient caching:

• Vector Storage: 384-dimensional embeddings for semantic search
• Entity Collections: Separate collections for spells, creatures, equipment, etc.
• Hybrid Search: Combine vector similarity with scalar filters
• Source Tracking: Records which API provided cached data
• Zero Configuration: Embedded database with no external dependencies

API Strategy

The project follows a strategic API assignment:

1. Use Open5e API for all content lookups
2. Prefer Open5e v2 over v1 when available
3. Unified source: Single API ensures consistent behavior and simplified maintenance

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

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and ensure tests pass
4. Run code quality checks: uv run pre-commit run --all-files
5. Commit your changes
6. 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
• FastMCP for the MCP server framework