Skip to main content
Glama

deeptutor-review-mcp

CI

A standalone MCP server for spaced-repetition review: it turns course material into review packs and gives any MCP-capable agent the tools to quiz you, grade your answers, track weak concepts, and export a printable page.

Ten tools, no DeepTutor web server required, no account required. Works over stdio (default) or Streamable HTTP.

review_specs  review_today  review_attempt  review_hint  review_weakness
review_export_link  review_export_tree  review_book_figures  review_generate  review_plan

1. Install

Python 3.11+.

git clone https://github.com/zkw90274-dot/deeptutor-review-mcp.git
cd deeptutor-review-mcp
python -m venv .venv
.venv/Scripts/activate          # Windows
# source .venv/bin/activate     # macOS / Linux
pip install .

This installs the MCP entry point deeptutor-review-mcp plus its dependencies from PyPI (deeptutor, deeptutor-mastery, fastapi, pydantic).

Use a regular install, not -e: the wheel also drops the module manifest into the shared deeptutor namespace, and an editable install does not merge that data file. Editing the source in place is still fine — re-run pip install . after changes.

Or install straight from git:

pip install "git+https://github.com/zkw90274-dot/deeptutor-review-mcp.git"

DeepTutor desktop app (optional)

The package also ships an entry definition for the DeepTutor desktop app's MCP store. If you use that app and want the review server to show up there:

deeptutor-review-catalog     # patches the app's catalog once, safe to re-run

Everything below works without this step — plain MCP clients connect directly.

Related MCP server: flashcards-mcp

2. Prove it works (no model, no knowledge base)

python examples/demo/seed.py     # writes demo-review-home/ with a 3-question pack
python examples/demo/smoke.py    # seeds a temp home, starts the MCP server, calls 3 tools

smoke.py starts the real server over stdio, checks that all ten tools are advertised, lists the pack and pulls today's queue. Exit code 0 means the whole surface is wired.

3. Connect your agent

stdio (Claude Desktop, DSH, Cursor, Claude Code, …):

{
  "mcpServers": {
    "deeptutor-review": {
      "command": "deeptutor-review-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "DEEPTUTOR_REVIEW_HOME": "/absolute/path/to/deeptutor-review-mcp/demo-review-home"
      }
    }
  }
}

Streamable HTTP (shared box, reverse proxy in front):

export DEEPTUTOR_REVIEW_MCP_TOKEN="$(python -c 'import secrets;print(secrets.token_urlsafe(32))')"
deeptutor-review-mcp --transport streamable-http --host 127.0.0.1 --port 8767 --path /mcp

Endpoint: http://127.0.0.1:8767/mcp, header Authorization: Bearer <token>. No token set means no auth — fine for loopback, not for anything reachable.

Then say to the agent:

List my review packs, then quiz me on the ones I have today.

4. What the ten tools do

Tool

Purpose

Needs a model?

Needs a knowledge base?

review_specs

List stored packs (id, title, item/concept counts, gate result)

no

no

review_today

Today's queue for one pack, answers withheld

no

no

review_attempt

Record a graded answer, return mastery projection + correction

no

no

review_hint

Graded hints (L1 pointer → L2 narrowing)

no

no

review_weakness

Rank weak concepts from history

no

no

review_export_link

One-pack offline HTML (single file)

no

no

review_export_tree

Whole library as <subject>/<chapter>.html + index

no

no

review_book_figures

Which figures a live-book section has

no

no

review_generate

Generate a new pack from one KB chapter (background job)

yes

yes

review_plan

Multi-week study plan, mirrored to calendar/task board

no (drafting a chapter note does)

yes

So: if you already have packs, nine of ten tools run fully offline. review_generate and the create action of review_plan read a DeepTutor knowledge base (<workspace>/knowledge_bases/<subject>/), and review_generate also needs a working model configured for DeepTutor (OPENAI_API_KEY / OPENAI_BASE_URL or the DeepTutor settings store).

5. Where state lives

Everything is per-workspace, in one directory:

Env var

Meaning

DEEPTUTOR_REVIEW_HOME

The review workspace (default: <DeepTutor workspace>/review). Holds review.sqlite3, exported HTML, drafts.

DEEPTUTOR_REVIEW_CACHE

Optional cache dir for rendered output.

DEEPTUTOR_REVIEW_MCP_TOKEN

Bearer token for the HTTP transport.

DEEPTUTOR_REVIEW_MCP_CONTEXT

Optional markdown file appended to the server's instructions.

DEEPTUTOR_REVIEW_PUBLIC_BASE_URL

Absolute prefix for review_export_link URLs (e.g. behind a reverse proxy).

Back up the home directory and you back up the learner's whole review history.

6. Slightly deeper

  • docs/usage-guide.md — the full operator guide: pack lifecycle, quality gates, plan templates, exports, troubleshooting.

  • docs/USAGE.md — tool-by-tool parameters and return shapes.

  • docs/skill/SKILL.md — the agent-facing skill: how an agent should talk to a learner while reviewing.

  • docs/maintainer-notes.md — validation log and design decisions from this repo's own runs.

7. Development

pip install -e ".[test]"
python -m pytest -q                 # unit + integration suite
python examples/demo/smoke.py        # end-to-end MCP handshake

CI runs both on Python 3.11 and 3.12 (see .github/workflows/ci.yml).

8. 中文速览

这是把「复习工坊」单独拆出来的 MCP 服务器,不需要 DeepTutor 网页端,也不依赖任何账号:

pip install -e .
python examples/demo/seed.py          # 造一个 3 题的演示复习包
deeptutor-review-mcp                  # stdio 启动,配置进你的 MCP 客户端即可

十个工具里九个离线可用(列包、今日队列、作答判分、分级提示、薄弱点、导出单包/整库、活书插图)。只有「从知识库生成新复习包」需要知识库 + 模型配置;「排多周学习计划」需要知识库章节。所有数据都在 DEEPTUTOR_REVIEW_HOME 指向的目录里,备份它等于备份全部复习记录。

License

MIT — see LICENSE.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers