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

Running the Server

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:

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:

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:

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

First-Run Setup

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

Configuration

Configure Milvus via environment variables:

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):

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

Development

Project Structure

Running Tests

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

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