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 调度算法与统计。

内置的三个学徒人设

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

也可以用 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 / 22 / 24（最低 20；dashboard 子命令依赖 open@11）。推荐 Node 22 LTS——仓库根目录有 .nvmrc，贡献者可用 nvm use / fnm use 对齐。

通过 npx apprentice-mcp 使用时，native 依赖会在你当前的 Node 版本下自动安装，无需手动编译。Node 版本详情与常见问题见下文 Node 版本与 troubleshooting。

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"]
    }
  }
}

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

环境变量

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

工具清单

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

可视化面板

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

npx apprentice-mcp dashboard

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

Node 版本与 troubleshooting

官方支持范围

package.json 中 engines.node 为 >=20。日常用户通过 npx 安装时，npm 会按运行时 Node 版本拉取 better-sqlite3 的预编译二进制，一般开箱即用。

核心原则

better-sqlite3 是原生 C++ 模块，.node 文件必须与运行时的 Node 大版本 ABI 一致。因此：

• npm install 与 node dist/index.js / MCP 启动应使用同一个 Node 大版本

• 切换 Node 大版本（如 22 → 24）后，需要重装或 rebuild native 依赖

常见错误：NODE_MODULE_VERSION 不匹配

启动 MCP 或跑测试时出现类似报错：

Error: The module '.../better_sqlite3.node' was compiled against a different Node.js version
using NODE_MODULE_VERSION 127. This version of Node.js requires NODE_MODULE_VERSION 137.

说明 better-sqlite3 是在旧 Node 版本下安装的，按以下步骤修复：

# 克隆仓库本地开发时
npm rebuild better-sqlite3

# 若仍失败，彻底重装（Windows 上若报 EPERM/EBUSY，先关闭 Cursor 里占用的 MCP 进程）
rm -rf node_modules
npm install

Windows PowerShell 等价命令：

Remove-Item -Recurse -Force node_modules
npm install

Windows 上 prebuild 下载失败

若 npm install 时 better-sqlite3 无法下载预编译包，会 fallback 到 node-gyp 本地编译，需要：

• Visual Studio Build Tools（勾选「使用 C++ 的桌面开发」）

• 或改用 WSL / Linux 环境开发

MCP 配置建议

普通用户（推荐，自动适配本机 Node）：

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

本地开发（指向仓库编译产物）：

{
  "mcpServers": {
    "apprentice-mcp": {
      "command": "node",
      "args": ["<你的仓库路径>/dist/index.js"]
    }
  }
}

本地开发时修改源码后需先 npm run build；切换 Node 大版本后需 npm rebuild better-sqlite3 或重装 node_modules。

本地开发

nvm use          # 或 fnm use — 对齐 .nvmrc（Node 22）
npm install
npm run dev      # 用 tsx 直接运行 src/index.ts
npm test         # 跑单元测试（vitest + 内存 SQLite）
npm run build    # 编译到 dist/

License

MIT