ExpertPack MCP

ep-mcp

通过模型上下文协议提供专家知识即服务。

一个 MCP 服务，可将任意 ExpertPack 转换为实时、可查询的知识服务。任何兼容 MCP 的 Agent（Claude Desktop、Cursor、Windsurf、Claude.ai、自定义宿主）都能连接并通过标准化工具获取高质量、来源信息丰富的领域专业知识。

🌐 expertpack.ai · 📦 ExpertPack 框架 · 📖 架构

在针对生产环境 v4.1 原子概念包（658 个分块）的 22 个问题基准测试中，检索命中率为 97.6%，完全未命中数为 0。同一知识包和评估集在此前 v4.0 基线中的结果为 65.1%。

功能

• 感知架构的混合检索：BM25 + 向量搜索（sqlite-vec）、元数据加权、MMR 重排、自适应阈值过滤、长度惩罚
• requires: 扩展（schema v4.1 atomic-conceptual）：当某个 top-K 原子条目的 frontmatter 声明 requires: [B, C] 时，系统会自动将引用的原子条目追加到结果中，作为标记为 requires_expanded=True 的额外 SearchResult。扩展具有方向性（A→B 不代表 B→A），最多传递 2 跳，最多包含 3 个原子条目且累计不超过 3,500 个 token，并在 max_results 切片之后追加，因此绝不会挤占 top-K 结果。
• 感知意图的路由：自动对查询进行分类（ENTITY/HOW/WHY/WHEN/GENERAL），并按查询调整向量/BM25 融合权重——无需 LLM
• 查询嵌入缓存：基于 SQLite 的缓存，以 (model, dimension, sha256(query)) 为键——热查询延迟从约 4 秒（实时 Gemini API）降至约 1 毫秒
• 深度图遍历：可选地通过知识图谱边执行多跳 BFS 扩展，并为每跳应用分数衰减以防止偏移
• 预留槽位图合并：可配置最终 top-K 中受保护的预留槽位，用于图扩展邻居，因此即使核心结果占据主导，相关文件也能显示出来
• BM25 回退模式：嵌入提供方不可用时，会优雅地降级为纯词法搜索（覆盖率 + 密度 + 路径 + 长度评分），而不是直接报错
• 交叉编码器重排器：可选的第二阶段精确度重排器（默认禁用，启用时热延迟约为 70 毫秒）
• 优先追溯来源：每个结果都包含 id、content_hash、verified_at、source_file
• 重构模式（RFC-003）：选择启用 reconstruct=true / reconstruct: true 后，结果会附带 fragment_id、line_range、original_markdown、跨度级 content_hash、excerpt、stale 和字节偏移量，使 Agent 能准确证明答案所依据的源文本
• EP 原生分块：文件作为原子检索单元处理（只有内容过长时才在 ##/### 处分割）。拆分后的分块保留原始跨度作为 content/span_hash，携带计算得出的 line_range，并记录 heading_path（0.7.0+）
• 标题路径（0.7.0+）：每个命中结果都带有 heading_path（例如 ["Routing", "Setup", "Ports"]），因此 H3 命中结果会保留其 H2 父级；ep_read(path, section=..., neighbors=true) 只读取该章节及其前后相邻章节
• 时效性（0.7.0+，ExpertPack Core 4.2）：命中结果和 ep_read 会附带 verified_age_days、age_stale（verified_at 早于文件的 refresh 或清单中的 freshness.refresh_cycle）、expired 和 expires_at（可变内容的 TTL）。stale 保持原有含义——索引漂移（文件自建立索引后发生变化，仅适用于重构模式）。可选通过 retrieval.freshness_penalty 下调排名（默认值为 0.0 = 关闭）
• 通过 MCP 提供 Skills（0.7.0+，可选启用）：在某个包的 manifest.yaml 中设置 mcp.skills.enabled: true，即可声明 io.modelcontextprotocol/skills 扩展（SEP-2640）。每个包对应一个位于 skill://{slug}/SKILL.md 的技能（自动生成），每个非 on_demand 文件均通过 skill://{slug}/{path} 原样提供；skills/list / skills/get 会发布包含 SHA-256 摘要、大小、ttlMs 和 cacheScope 的清单。目前宿主支持仍有限，因此 ep_* 工具仍是主要使用方式
• 感知 frontmatter：提取嵌入内容中的元数据，并提取 type、tags、requires 等字段用于加权/扩展/筛选
• 增量索引：基于内容哈希检测过时内容——仅对发生变化的文件重新生成嵌入
• 多包支持：在 /packs/{slug}/mcp 根据路径路由
• 感知图谱的检索：可选在检索后通过 _graph.yaml 邻接关系进行扩展；当图谱导出提供了本体/实体节点时，也会包含已接受的节点
• context_prefix（RFC-004）：在索引时将侧边文件中的情境说明字符串添加到嵌入和 BM25 检索文本前；返回文本/重构文本仍为原始原子条目正文
• 层级 / 导航筛选器：retrieval_strategy: navigation、_index.md、source-coverage.md 和 context.on_demand 文件会从 RAG 池中排除（仍可通过 ep_read / 资源读取）
• 工具：
  • ep_search — 主要的混合检索工具
  • ep_read — 按路径或来源 ID 加载整个原子条目（消费循环第 2 步）
  • ep_list_topics — 浏览包结构和可用内容类型
  • ep_graph_traverse
  • 多包 stdio 支持：所有工具都接受 pack 参数，以便在配置了多个包时进行路由。单包配置中 pack 为可选项（默认使用唯一配置的包）。
• 资源：
  • ep://{slug}/manifest
  • ep://{slug}/authority
  • ep://{slug}/files
  • ep://{slug}/file/{+path}（包含 frontmatter 的原始内容）
  • skill://{slug}/SKILL.md、skill://{slug}/{+path}（仅当 mcp.skills.enabled: true 时）
• 传输方式：Streamable HTTP（主要方式，适用于云端）、stdio（本地开发）
  • stdio 多包支持（0.6.0+）：使用 --transport stdio 且配置了多个包时，所有工具都接受可选的 pack 参数（slug 字符串），用于指定要查询的包。单包配置中 pack 为可选项，默认使用唯一配置的包。这样，MCP 宿主（Cursor、Claude Desktop）可以通过单个 stdio 进程使用多个包，无需每个包启动一个进程。
• HTTP 端点：GET /search（供非 MCP HTTP 客户端使用）
• 黄金检索评估（0.7.0+）：tests/eval/ — YAML 查询集（按最佳结果优先的 expected、must_not、category），按包和类别计算 recall@1/3/5、MRR 以及 must_not 违规次数。默认运行时跳过；使用 EP_EVAL_TODAY=2026-10-20 和可选的 EP_EVAL_MIN="recall@5=0.9,mrr=0.7" 运行 pytest tests/eval -m golden --golden <dir> --packs-root <dir>，或运行 python tests/eval/golden_eval.py --golden <dir> --today 2026-10-20
• 身份验证：API 密钥（第 1 阶段），设计上支持 OAuth 2.1（第 2 阶段）

快速开始

安装

git clone https://github.com/brianhearn/ep-mcp.git
cd ep-mcp
pip install -e .[dev]

配置

创建 config.yaml，至少包含：

server:
  host: "127.0.0.1"
  port: 8000
  log_level: "info"
  # Required for public Host headers (SDK v2 DNS-rebinding protection).
  # See DEPLOYMENT.md — omit and Streamable HTTP returns 421.
  mcp_allowed_hosts:
    - "localhost"
    - "localhost:*"
    - "127.0.0.1"
    - "127.0.0.1:*"

packs:
  - slug: "my-pack"
    path: "/path/to/your/expertpack"
    api_keys:
      - "your-secret-key-here"

embedding:
  provider: "gemini"           # "gemini" (default) or "azure-openai"
  model: "gemini-embedding-001"

完整配置参考——包括嵌入提供方、检索调优（mmr_lambda、min_score、default_max_results、图扩展、重排器、requires: 扩展等）、生产环境 systemd 配置和部署注意事项——请参阅 DEPLOYMENT.md。

运行

ep-mcp serve --config config.yaml

服务启动时会构建／更新 SQLite 索引（FTS5 + sqlite-vec）。0.5.0 需要重建现有索引（index_features=context_prefix_v1+nav_filter_v1）；启动时会自动完成，也可以先删除 <pack>/.ep-mcp/。

GET /search HTTP 端点可通过以下地址访问：

GET /search?q=<query>&pack=<slug>&n=10

添加 &reconstruct=true，即可包含原始 Markdown 片段和来源信息块，以供核验。

请求头为 Authorization: Bearer <key>。

环境变量

只需配置所用嵌入提供方的密钥。

变量	必需	说明
GEMINI_API_KEY	如果 embedding.provider: gemini	Gemini 嵌入 API 密钥
AZURE_OPENAI_ENDPOINT	如果 embedding.provider: azure-openai	Azure OpenAI 资源端点
AZURE_OPENAI_API_KEY	如果 embedding.provider: azure-openai	Azure OpenAI API 密钥
EP_MCP_KEY_{SLUG}	可选	每个知识包的 API 密钥覆盖项（slug 转为大写，连字符替换为下划线）
EP_MCP_REMOTE_HOST	可选	scripts/deploy.sh 的部署目标
EP_MCP_REMOTE_SRC	可选	deploy.sh 的远程源路径
EP_MCP_REMOTE_SITE_PKG	可选	deploy.sh 的远程 site-packages 路径

技术栈

• 语言：Python 3.12+
• MCP 框架：官方 mcp SDK v2（MCPServer，规范 2026-07-28，与 2025 年客户端双时代兼容）
• 存储：SQLite，搭配 FTS5 + sqlite-vec
• 嵌入：Gemini（默认），可配置 Azure OpenAI / OpenAI 提供方
• Web：Starlette + Uvicorn（用于 Streamable HTTP）
• CLI：Click

确切依赖项请参阅 pyproject.toml。

项目结构

详细的模块划分、检索流程、索引策略和设计决策，请参阅 ARCHITECTURE.md。

相关项目

• expertpack.ai — 框架网站、社区知识包和文档
• ExpertPack — 架构框架、验证工具、Obsidian 兼容性和社区知识包
• ExpertPacks — 已发布的知识包（私有）
• EasyTerritory MCP（未来）— 构建于此代码库和 ezt-designer 知识包之上的领域专用层

许可证

Apache 2.0 © 2026 Brian Hearn

作者

Brian Hearn — 3 天内构建完成（2026 年 4 月 10–11 日）。