Skip to main content
Glama

srs-mcp — 间隔重复,作为一个 MCP 服务器

让任何支持 MCP 的代理(Claude Code、Claude Desktop 或任何其他 MCP 主机)拥有真正的、按计划正确安排的间隔重复记忆,而不是每次 会话都手动从 markdown 表格中重新推导“今天该复习什么”。实现了 SM-2(Anki/SuperMemo 背后的算法)作为四个可调用工具,由本地 SQLite 文件支持。无需账户,无网络调用,无遥测——一切都在你的机器上运行。

状态:原型,尚未在任何地方发布。 已在本地构建并验证(见下文“如何验证”);尚未被本项目以外的任何人安装。请将版本 0.2.0 视为预发布版本。

为什么存在

Markdown 检查清单和词汇表是人们(以及帮助他们代理)跟踪复习内容的常见方式,但没有任何东西从中计算出实际的时间表——“今天到期”最终只是猜测,每次都要靠眼睛重新阅读。srs-mcp 是缺失的一环:一个小的、真实的调度算法以工具的形式暴露出来,因此代理可以跟踪任何内容的复习状态——闪卡、面试问题、词汇、入职测验——而无需在提示中重新实现 SM-2。

Related MCP server: FlashLearn

四个核心工具(免费、无限、永久)

工具

功能

add_item(topic, question, answer)

在某个主题下添加一个复习项。新项目立即可用。

get_due_items(topic="", limit=10)

列出今天到期或逾期的项目。在评分之前不显示答案,就像真正的闪卡复习一样。

grade_item(item_id, quality)

对回忆质量进行 0–5 评分(5 = 完美,<3 = 失败/重置)。通过 SM-2 返回下一个到期日期和正确答案。

get_stats(topic="")

总数、今天到期数量、平均难度系数。

获取 Pro

两个额外的工具被 Pro 许可证门控——这是 srs-mcp 使用的免费/付费分割,而不是订阅或托管后端:

工具

功能

export_items(topic="", format="json"|"csv")

批量导出/备份所有复习数据。

get_forecast(topic="", days=30)

复习负载预测——未来 N 天每天有多少项目到期,以便在堆积发生之前可见。

许可机制具体如何运作: srs-mcp 使用 Ed25519 私钥签署许可证密钥,该私钥永远不会离开维护者的机器;此仓库仅附带匹配的公钥(license.py),它可以验证签名但无法伪造签名。购买密钥,将其设置为 SRS_LICENSE_KEY(环境变量)或保存到 ~/.srs-mcp/license.key,Pro 工具就会解锁——无需账户,无电话回家检查,可离线工作。有关完整机制及其声明的限制,请参阅 license.py(简短版本:这可以阻止随意复制,它不是 DRM——没有什么能阻止某人在自己的开源 Python 文件本地副本中修补掉检查;请参阅模块文档字符串以了解此权衡的诚实版本)。

目前还没有实时购买链接。 本节描述的是机制,该机制已构建并测试(见 test_license_gate.py),而不是一个可用的商店。当购买流程存在时,它会放在这里。

安装

需要 Python 3.11+。

git clone <repo-url>   # not yet public — see status note above
cd srs-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/srs-mcp       # runs the server on stdio

要将其用作 Claude Code 插件,请将 Claude Code 指向此目录 (或发布后,指向其市场列表)——.claude-plugin/plugin.json 和 .mcp.json 已设置好;服务器读取 SRS_DB_PATH,因此 插件安装的数据在更新后仍然存在(在 Claude Code 下为 ${CLAUDE_PLUGIN_DATA}/srs.db,或直接/手动运行时为同目录下的 srs.db)。

如何验证

不仅仅是“它可以导入”——实际上是通过真实的 MCP 协议运行的:

  • test_client.py 将 server.py 作为子进程启动(与真实 MCP 主机相同的方式),驱动完整的添加/列表/评分/列表会话,并在测试框架之外独立重新检查生成的 SQLite 行。

  • test_license_gate.py 以三种方式启动服务器(无许可证、有效许可证、篡改许可证),并确认 export_items / get_forecast 在情况 1 和 3 中拒绝,在情况 2 中返回真实数据——证明许可证检查是一个真正的门,而不是空操作。

  • ingest_chinese_vocab.py 和 ingest_leetcode.py 是可工作的、幂等的摄取脚本,通过真实的 add_item MCP 调用(而不是直接 SQLite 写入)从本项目的 markdown 跟踪器中填充真实的个人数据(114 个中文词汇项,16 个已完成的 LeetCode 问题)。

与“准备发布”之间的诚实差距——没有四舍五入

  1. 没有公共仓库。 每个真正的分发路径(Claude Code 的社区插件市场、GitHub 发布、MCP 目录列表)都需要在公共 git URL 上可访问。此项目仅限本地。创建它(一个 GitHub 仓库,可能还有一个账户)超出了本项目当前的自主范围,除非有明确的批准——以上所有内容都已准备好,一旦获得批准,这只是一个复制和推送的操作,而不是构建任务。

  2. 无法针对 claude plugin validate 进行自我验证。 此开发环境中没有 claude CLI 或 Node/npx。插件清单在仔细阅读 Anthropic 文档并交叉引用他们自己的生产 marketplace.json 的范围内符合模式,但未经机器验证。

  3. 没有实时购买流程。 许可证机制是真实的且经过测试;将其变成实际销售需要一个商店(Ko-fi、Gumroad 或类似),目前尚不存在——这是一个创建账户的步骤,超出了本项目的自主范围,除非获得批准。

  4. 许可证执行基于诚实,而非防篡改,这是设计使然,也是因为发布可读 Python 的本质——请参阅上面的“获取 Pro”部分和 license.py 的文档字符串。

  5. 没有认证/多租户方案。 单个本地 SQLite 文件,单个用户。对于当前的“在你的机器上运行”模型来说没问题;要成为托管/团队产品,需要真正的设计工作。

  6. 零外部验证。 本项目之外没有人安装或使用过它。以上每项声明都是“这按构建和测试的方式工作”,而不是“人们想要这个”。

许可证

MIT——见 LICENSE。(Pro 层的 许可证密钥机制 与代码本身的 MIT 许可证是分开的——请参阅上面的“获取 Pro”。)

Available Tools

6 tools
add_itemA

Add a new spaced-repetition item (e.g. a LeetCode problem, a Chinese vocab word, an interview question) under a topic. New items are due immediately.

Inputs: topic (required), answer (required), question (required).

export_itemsA

[Pro] Export items (id, topic, question, answer, interval_days, repetitions, ease_factor, due_date, created_at) as json or csv text, optionally filtered to one topic. Requires a valid Pro license (see README's "Get Pro" section) -- this is the free/Pro split's first concrete gate: the 4 core tools stay free and unlimited forever, bulk export/backup is part of the paid tier. Without a valid license, returns an upgrade message instead of data, not an error the caller has to guess the meaning of.

Inputs: topic, format.

get_due_itemsA

List items due for review today (or overdue), optionally filtered to one topic. Returns id, topic, question (answer withheld until grade_item is called, same as a real flashcard review).

Inputs: limit, topic.

get_forecastA

[Pro] Review-load forecast: how many items become due on each of the next N days, optionally filtered to one topic. Lets a user see an upcoming pile-up before it happens instead of discovering it the day of -- a real planning feature, not a gate for its own sake. Requires a valid Pro license, same as export_items.

Inputs: days, topic.

get_statsA

Summary stats: total items, how many due today, average ease factor, optionally scoped to one topic.

Inputs: topic.

grade_itemA

Grade recall quality for an item just reviewed (0-5: 0 = total blackout, 3 = correct with effort, 5 = perfect instant recall) and return the newly computed next-due date, plus the correct answer for confirmation. Uses SM-2 scheduling.

Inputs: item_id (required), quality (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool serves a clearly distinct purpose: adding items, fetching due items, grading recall, viewing stats, exporting data, and forecasting workload. There is no overlap or ambiguity in their intended actions.

    Naming Consistency5/5

    Every tool follows a consistent verb_noun pattern (add_item, get_due_items, grade_item, get_stats, export_items, get_forecast), making it easy to infer the action and target. No mixed conventions or vague verbs.

    Tool Count5/5

    With 6 tools, the server is well-scoped for a spaced-repetition system, covering the core workflows (add, review, stats, export, forecast) without unnecessary bloat or excessive granularity.

    Completeness4/5

    The tool surface covers the primary lifecycle (add, review, stats, export, forecast) well, but lacks direct update and delete operations for items. Export tools can serve as a workaround, so the gap is minor.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables agents to perform spaced-repetition learning with FSRS scheduling, including adding cards, reviewing due cards, and grading recall, using a headless SQLite or Postgres backend.
      9
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local Leitner flashcard MCP server enabling AI clients to create decks, manage cards, study with spaced repetition, and track progress.
      MIT