Skip to main content
Glama

LoreKeeper MCP

by frap129
GitHub
Python
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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 uv run python -m lorekeeper_mcp # Or with custom configuration LOG_LEVEL=DEBUG uv run python -m lorekeeper_mcp

Available Tools

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

  1. lookup_spell - Search spells by name, level, school, class, and properties

  2. lookup_creature - Find monsters by name, CR, type, and size

  3. lookup_character_option - Get classes, races, backgrounds, and feats

  4. lookup_equipment - Search weapons, armor, and magic items

  5. lookup_rule - Look up game rules, conditions, and reference information

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

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:

  1. Prefer Open5e API over D&D 5e API

  2. Prefer Open5e v2 over v1 when available

  3. Use D&D 5e API only for content not available in Open5e (primarily rules)

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

  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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Provides fast, cached access to comprehensive Dungeons & Dragons 5th Edition data including spells, monsters, classes, races, equipment, and rules through Open5e and D&D 5e APIs.

  1. Features
    1. Quick Start
      1. Prerequisites
      2. Installation
      3. Running the Server
    2. Available Tools
      1. Configuration
        1. Development
          1. Project Structure
          2. Running Tests
          3. Code Quality
          4. Database Cache
          5. API Strategy
        2. 📋 OpenSpec Integration
          1. Contributing
            1. Development Workflow
            2. Testing
          2. License
            1. Acknowledgments

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/frap129/lorekeeper-mcp'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server