Errorbook MCP

Local-first error notebook infrastructure for MCP agents, with FSRS scheduling and printable math PDFs.

Errorbook MCP 是一个可直接接入支持 Model Context Protocol (MCP) 的 agent 的错题管理服务。图片识别由 agent 自己的视觉能力完成；MCP 负责接收结构化题干、稳定编号、去重、复习调度、优先级维护，以及生成带数学公式的打印版 PDF。

核心设计

• 题目使用不可变编号（例如 EB-2026-000001），编辑不会换号。

• 复习间隔由版本锁定的 FSRS 算法维护；重复答错会缩短间隔并增加错题权重。

• 用户手动提高优先级会记录为独立事件，并随时间衰减，不会让旧题永久占据队首。

• 所有关键写操作支持幂等键；agent 重试不会重复录题或重复记一次作答。

• 每份 PDF 使用题目快照。之后修改题目不会改变已经生成的试卷。

• SQLite 默认启用 WAL、外键和写事务，适合本地单用户 agent 并发调用。

Related MCP server: Bruin

MCP 能力

所有有副作用的操作都接收 idempotency_key。建议 agent 使用“用户会话/动作类型/随机 UUID”组成的 8-128 字符键，并在网络重试时保持不变。

记忆与选卷算法

系统明确分开两个问题：FSRS 决定“下一次何时复习”，队列评分决定“本周容量有限时先打印哪些题”。人工优先级不会篡改 FSRS 状态。

复习结果映射如下：

默认 desired_retention=0.90，使用依赖锁定的 FSRS 6.x 官方实现。普通“答对”必须记为 Good，不能由 agent 擅自升级为 Easy。mastered 题再次做错或部分正确会自动恢复为 active。

近期错误压力按 42 天半衰期衰减并在 6 封顶；人工 boost 按 14 天半衰期衰减并在正负 5 封顶。两者进入评分前都经过 1 - exp(-mass) 饱和，历史错误次数不会线性累加并永久霸榜。

周卷基础分为：

score = 42% 到期紧迫度
      + 22% 近期错误压力
      + 12% FSRS 难度
      + 10% 人工 boost
      +  8% 用户长期 importance
      +  6% 距离上次入卷时间

到期紧迫度在到期点为 0.5，随逾期连续上升并趋近 1；未来到期则连续下降。默认候选仅包含 active 且在未来七天内到期的题，或仍有有效人工 boost 的题。已经成功进入试卷的题冷却 6 天；若入卷后又做错，则立即重新获得资格。已到期且 28 天未入卷的题进入 fairness_must_include 必选桶，防止大题库中长期饥饿。返回结果会报告 backlog、必选溢出和按当前卷容量估算的清空周数。

题库过载时算法不能凭空消除工作量：如果每周新增/到期数量长期高于 max_questions，agent 应把返回的 backlog 明确告诉用户，而不是悄悄丢题。

安装

需要 Python 3.11+、uv 和 Chromium 系浏览器。Windows 会自动寻找 Microsoft Edge。

git clone https://github.com/stardustlil/errorbook-mcp.git
Set-Location errorbook-mcp
uv sync --locked
uv run errorbook-mcp

环境变量不会自动读取 .env；请在 MCP 客户端配置中直接设置。最小配置示例：

{
  "mcpServers": {
    "errorbook": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\errorbook", "run", "errorbook-mcp"],
      "env": {
        "ERRORBOOK_DATA_DIR": "C:\\path\\to\\errorbook-data",
        "ERRORBOOK_TIMEZONE": "Asia/Tokyo"
      }
    }
  }
}

Hermes Agent

Hermes Agent v0.18+ 可以通过 stdio 直接加载全部工具。先完成上面的 uv sync --locked，再执行：

hermes mcp add errorbook `
  --command ".venv\Scripts\python.exe" `
  --connect-timeout 30 `
  --env "ERRORBOOK_DATA_DIR=$env:LOCALAPPDATA\errorbook-data" "ERRORBOOK_TIMEZONE=Asia/Tokyo" `
  --args -m errorbook_mcp

当 Hermes 询问是否启用全部工具时直接回车，然后验证：

hermes mcp test errorbook
hermes mcp list

请启动一个新的 Hermes 会话使配置生效。图片 OCR 由 Hermes 当前选择的视觉模型完成，因此该模型必须支持图片输入。

也可以直接运行模块：

uv run python -m errorbook_mcp

Agent 录题流程

1. 用户把错题图片上传给具备视觉能力的 agent。

2. agent 使用 MCP prompt record_from_image 的规则，将图片忠实转写成 Markdown；数学公式使用 $...$ 或 $$...$$ LaTeX。

3. agent 调用 create_problem。OCR 不清楚的内容不能猜，应先向用户确认。

4. MCP 校验题型、选项和答案，检查重复内容，并分配固定编号。

一个题目只保存规范化后的文本；原始图片仍由宿主应用管理。这样不需要在 MCP 中配置第二套视觉模型或上传凭据。

复习与出卷

• 做错后调用 record_review(outcome="incorrect")；这既保留历史，也会通过 FSRS 自动提前下次复习。

• 用户明确说“提高 EB-2026-000123 的优先级”时调用 adjust_priority。不要用优先级工具伪造一次作答。

• 每周调用 create_review_sheet，默认选择已经到期和未来七天内到期的题目，并生成问题卷；可以选择额外生成答案册。

• 工具返回本地绝对路径、SHA-256 和 errorbook://exports/... MCP resource URI。

PDF 将原始 Markdown 转为静态 MathML，再由本机 Edge/Chrome/Chromium 打印，不执行 JavaScript 或 TeX 程序。原始 HTML、外部图片、链接和危险 LaTeX 命令会被拒绝。资源读取时会重新核对 SHA-256；文件被替换或损坏时不会静默返回。

导出使用数据库租约。进程在渲染中退出时，原幂等键会先保持 generating；租约最多五分钟后，同一请求和同一幂等键可从已冻结的题目快照恢复，不会重新选题。只有问题卷实际生成成功后，题目才会记为“已入卷”。

数据与备份

默认数据目录是当前目录下的 data/：

data/
  errorbook.sqlite3
  exports/
  tmp/

停止 MCP 服务后，备份整个数据目录即可。不要只复制 SQLite 主文件而遗漏仍在使用中的 WAL 文件。

开发验证

uv sync --extra dev
uv run pytest

测试覆盖数据库事务、并发稳定编号、幂等与崩溃恢复、FSRS 状态更新、优先级衰减、公平选卷、MCP stdio 往返、公式安全、PDF 文件完整性和真实浏览器渲染。

构建可分发 wheel：

uv build

安全边界

• MCP 不读取任意图片路径，也不向外部 OCR 服务发送题目。

• 题干按纯 Markdown 处理，原始 HTML 被转义；LaTeX 只转换为 MathML，不执行 TeX 命令。

• stdio 模式的日志只写入 stderr，避免破坏 MCP 协议帧。

• 远程 streamable HTTP 部署需要由反向代理提供 TLS、认证和单用户隔离；默认配置面向本地 stdio。

• streamable HTTP 模式本身不提供多租户隔离。不要把默认服务直接暴露到公网。

参与项目

开发流程见 CONTRIBUTING.md，架构与一致性边界见 docs/architecture.md。安全问题请按 SECURITY.md 私下报告，不要在公开 issue 中附带真实题目、数据库或访问凭据。