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 并发调用。

MCP 能力

类型	名称	用途
Prompt	record_from_image	约束宿主视觉模型忠实转写图片，模糊内容先确认，公式输出为 Markdown + LaTeX
Tool	create_problem	校验、去重、记录单题并分配固定编号
Tool	get_problem	按编号读取题目，可选完整复习和优先级历史
Tool	search_problems	按文本、编号、学科、标签、题型、状态和到期时间组合查询
Tool	update_problem	使用 expected_version 乐观锁修正 OCR 或答案内容
Tool	record_review	追加真实作答结果并更新 FSRS
Tool	adjust_priority	记录用户明确提出的临时优先级调整
Tool	set_problem_status	在 active、mastered、archived 之间切换，不硬删除历史
Tool	create_review_sheet	冻结题目快照并生成 A4 问题卷和可选答案册
Tool	get_export_status	查询导出状态、路径、资源 URI、大小和 SHA-256
Tool	get_library_stats	查看题库、到期积压和学科分布
Resource	errorbook://exports/{export_id}/{booklet}	读取 questions 或 answers PDF 二进制内容

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

记忆与选卷算法

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

复习结果映射如下：

实际结果	FSRS rating	行为
做错、空白、放弃	Again	缩短间隔，错误压力增加 1
部分正确、提示后正确	Hard	较短间隔，错误压力增加 0.5
独立正确	Good	正常增长稳定度，错误压力减半
明确轻松且无提示	Easy	更长间隔，错误压力降为四分之一
跳过	不评分	只留审计事件，不改变卡片状态

默认 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 中附带真实题目、数据库或访问凭据。