apprentice-mcp

一个开源的 MCP（Model Context Protocol）Server，为 Claude Desktop、Cursor、Windsurf 等任意支持 MCP 的 AI 客户端提供"长期学习跟踪"能力，基于学徒效应（观察 → 模仿 → 独立 → 精通）与间隔重复（FSRS 算法）帮你系统性地学习和巩固任意领域的知识/技能。

产品定位：角色反转的学徒

apprentice-mcp 采用角色反转的教学设计：你是"师傅"，AI 扮演"学徒"本人。你把知识点讲给学徒听，学徒像真实的人一样有理解、有疑问、有情绪地反馈——这是费曼学习法（教是最好的学）的落地：如果学徒总是似懂非懂、追问的问题正好戳中逻辑漏洞，说明你自己也没有真正吃透这块知识。

apprentice-mcp 本身不调用任何 LLM、不管理任何模型 API Key——学徒该怎么说话、什么时候表现出哪种情绪，完全由你正在用的 AI 客户端（Claude/Cursor 等）决定；apprentice-mcp 只负责确定性的存储、FSRS 调度算法与统计。

内置的三个学徒人设

不同难度的知识需要不同"心智水平"的学徒来陪练：

人设	年龄 / 认知阶段	适合场景
米娅 Mia	8 岁，具体运算阶段早期	给孩子讲重要概念前的"教学彩排"，或孩子自己用来加深理解
贝蒂 Betty	12 岁，具体运算→形式运算过渡阶段	给 10-13 岁孩子讲解前的排练，或需要一点抽象思维但还不到大学水平的知识
文森 Vincent	刚上大学的大一新生，形式运算成熟阶段	你自己学习强化学习、世界模型这类有门槛的知识，检验自己是不是真的能应用

也可以用 upsert_persona 自定义更多人设（比如给自己配一个更挑剔的"资深同行"，或给孩子配一个更年幼的"弟弟妹妹"）。完整的人设设计方法论见 docs/design/apprentice-mcp-design.md。

配套 Skill：让学徒真的"演"起来

apprentice-mcp 只提供确定性的存储和调度，学徒该怎么说话、怎么表现出五维人格（立场/情绪/记忆/边界/成长），需要配套的 Agent Skill 来落地。仓库自带 skill/apprentice-teaching/，安装本包后可以直接使用：

# 复制到个人 Skill 目录（对所有项目生效）
cp -r node_modules/apprentice-mcp/skill/apprentice-teaching ~/.cursor/skills/

# 或复制到某个项目的 Skill 目录（仅该项目生效）
cp -r node_modules/apprentice-mcp/skill/apprentice-teaching <your-project>/.cursor/skills/

复制后重启客户端，直接说"我来教教我的学徒 XX"、"考一下贝蒂"之类的话就会自动触发；完整的教学会话流程、人设语气参考、示例对话见 skill/apprentice-teaching/SKILL.md。

安装与配置

前置要求

Node.js 20+（dashboard 子命令依赖 open@11，要求 Node ≥ 20）。

Claude Desktop

编辑 claude_desktop_config.json（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json，Windows: %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "apprentice-mcp": {
      "command": "npx",
      "args": ["apprentice-mcp"]
    }
  }
}

Cursor

编辑项目或全局的 mcp.json：

{
  "mcpServers": {
    "apprentice-mcp": {
      "command": "npx",
      "args": ["apprentice-mcp"]
    }
  }
}

重启客户端后即可在对话中使用下面的工具。

环境变量

变量	说明	默认值
APPRENTICE_MCP_DB_PATH	SQLite 数据文件路径	~/.apprentice-mcp/data.db

数据库文件首次启动时自动创建并建表，无需任何额外配置。

工具清单

工具	参数	说明
add_item	subject, topic?, title, content, tags?, masteryStage?, personaId?	新增知识点/技能条目，自动初始化 FSRS 状态
list_items	subject?, tag?, masteryStage?, personaId?, limit?, offset?	按条件筛选查看条目
update_item	itemId, 可更新字段	修改条目内容/标签/mastery_stage/关联人设
delete_item	itemId	级联删除相关复习状态与历史
get_due_reviews	limit?, personaId?	取出当前到期需要复习的条目，按到期时间升序
record_review	itemId, rating(again/hard/good/easy), correct?, timeSpentSec?, notes?	记录一次练习结果，驱动 FSRS 更新复习计划
record_error	itemId?, category, description?, occurredAt?	记录一次错误分类
get_error_patterns	subject?, itemId?, limit?	按类别汇总反复出现的错误类型，用于"举一反三"
get_progress_summary	itemId?, subject?, personaId?	复习次数、正确率趋势、mastery_stage 分布统计
list_personas	isBuiltin?	查看学徒人设列表（内置 3 个 + 全部自定义）
upsert_persona	id?, name, ageLabel?, cognitiveStage?, traits	新增或更新一个自定义学徒人设（内置人设禁止修改）
delete_persona	personaId	删除一个自定义学徒人设（内置人设禁止删除）

详细的设计思路（学徒效应方法论、五维人格框架、认知发展阶段与人设的对应关系）见 docs/design/apprentice-mcp-design.md。

可视化面板

查看当前所有知识点的掌握度分布（整体 / 按主题 / 按人设）：

npx apprentice-mcp dashboard

会在本地起一个只读的小型 web server 并自动打开浏览器，数据来自同一个 SQLite 文件，随时刷新页面看最新进度。

本地开发

npm install
npm run dev      # 用 tsx 直接运行 src/index.ts
npm test         # 跑单元测试（vitest + 内存 SQLite）
npm run build    # 编译到 dist/

License

MIT