LoreKeeper MCP
用于使用AI助手查找D&D5e信息的模型上下文协议（MCP）服务器。LoreKeeper通过Open5e API提供对Dungeons&Dragons第五版全面数据的快速缓存访问。
特性
- 全面的D&D 5e数据：访问法术、怪物、职业、种族、装备和规则
- 语义搜索：具有自然语言搜索功能的Milvus Lite矢量数据库
- Open5e API集成：通过Open5e API访问全面的D&D 5e内容
- 类型安全配置：基于Pydantic的配置管理
- 现代Python堆栈：使用Python 3.11+、异步/等待模式和FastMCP构建
- 生产就绪：全面的测试套件、代码质量工具和预提交挂钩
快速开始
先决条件
- Python 3.11或更高版本
- 紫外线 用于包管理
安装
# 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运行服务器
# 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可用工具
LoreKeeper提供6个MCP工具用于查询D&D 5e游戏数据：
search_spell-按姓名、级别、学校、班级和属性搜索法术search_creature-按名称、CR、类型和大小查找怪物search_character_option-获取课程、种族、背景和技能search_equipment-搜索武器、盔甲和魔法物品search_rule-查找游戏规则、条件和参考信息search_all-通过语义搜索跨所有内容类型进行统一搜索
看 docs/tools.md 详细用法和示例。
文档筛选
所有查找工具和搜索工具都支持按源文档过滤：
# 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"]
)这使您能够：
- 仅限于搜索SRD（免费）内容
- 按特定出版书籍或增刊筛选
- 将自制程序与官方内容分开
- 控制您出于许可原因使用的源
看 docs/document-filtering.md 以获取全面的指导和跨源过滤示例。
CLI使用情况
LoreKeeper包括一个用于导入D&D内容的命令行界面：
# Import content from OrcBrew file
lorekeeper import MegaPak_-_WotC_Books.orcbrew
# Show help
lorekeeper --help
lorekeeper import --help看 docs/cli-usage.md 获取详细的CLI文档。
配置
LoreKeeper使用环境变量进行配置。所有设置都使用 LOREKEEPER_ 前缀。创建一个 .env 文件：
# 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语义搜索
LoreKeeper使用 Milvus Lite 作为默认的缓存后端，提供由向量嵌入支持的语义搜索功能。
特性
- 语义搜索：按含义查找内容，而不仅仅是精确的文本匹配
- 矢量嵌入：使用句子转换器进行高质量的文本嵌入
- 混合搜索：将语义查询与结构化过滤器相结合
- 零配置：使用合理的默认值即可开箱即用
- 轻量级：嵌入式数据库，无需外部服务
使用示例
# 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")首次运行设置
第一次运行时，LoreKeeper下载嵌入模型（约80MB）。这是一次性下载：
# First run will show:
# Downloading model 'all-MiniLM-L6-v2'...
lorekeeper serve配置
通过环境变量配置Milvus：
# 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从SQLite迁移
如果您使用的是带有SQLite缓存的旧版本：
- 将后端设置为Milvus（默认）：
LOREKEEPER_CACHE_BACKEND=milvus- 重新导入数据（Milvus缓存开始为空）：
lorekeeper import /path/to/content.orcbrew- 或者让它在第一次查询时从API重新填充。
回滚：要继续使用SQLite（无语义搜索）：
LOREKEEPER_CACHE_BACKEND=sqlite
LOREKEEPER_DB_PATH=./data/cache.db注意：SQLite缓存不支持语义搜索，只支持精确匹配和模式匹配。
发展
项目结构
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运行测试
# 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代码质量
该项目使用了几个代码质量工具：
- 黑色：代码格式（100个字符行长度）
- 拉夫：梳理和进口分拣
- MyPy 的：静态类型检查
- 预承诺：用于自动检查的Git挂钩
# 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矢量数据库缓存
LoreKeeper使用Milvus Lite进行语义搜索和高效缓存：
- 向量存储：384维语义搜索嵌入
- 实体集合：单独收藏法术、生物、装备等。
- 混合搜索：将向量相似性与标量过滤器相结合
- 源追踪：API提供缓存数据的记录
- 零配置：没有外部依赖关系的嵌入式数据库
API战略
该项目遵循API战略任务：
- 使用Open5e API 用于所有内容查找
- 更喜欢Open5e v2 超过v1（可用时）
- 统一来源：单个API可确保一致的行为和简化的维护
看 docs/tools.md 以获取详细的API映射和实现说明。
📋 OpenSpec集成
此项目使用 开放规范 作为规范管理和变更跟踪的核心开发工具。OpenSpec提供：
- 结构化规范：所有功能、API和架构更改都记录在详细的规范中
- 变更管理：对提案、设计和实施任务进行全面的变更跟踪
- 生活文档：规范随着代码库而发展，确保文档保持最新
- 开发工作流程：规范、实现和测试之间的集成
这 openspec/ 目录包含：
- 所有项目组件的当前规范
- 具有完整上下文的历史变更记录
- 设计文件和实施计划
- 开发工作的任务分解
投稿时，请查阅相关规范 openspec/ 并遵循既定的变更管理流程。
贡献
我们欢迎捐款！请查看我们的 贡献指南 了解详情。
开发工作流程
- 复刻仓库
- 创建要素分支：
git checkout -b feature-name - 进行更改并确保测试通过
- 运行代码质量检查：
uv run pre-commit run --all-files - 提交您的更改
- 推到叉子上，创建一个拉取请求
测试
所有贡献必须包括测试：
- 新功能应具有相应的单元测试
- 保持测试覆盖率在90%以上
- 使用pytest夹具进行一致的测试设置
- 异步代码遵循async/await模式
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。