# 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`](docs/design/apprentice-mcp-design.md)。

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

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

```bash
# 复制到个人 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](#node-版本与-troubleshooting)。

### Claude Desktop

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

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

### Cursor

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

```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`](docs/design/apprentice-mcp-design.md)。

## 可视化面板

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

```bash
npx apprentice-mcp dashboard
```

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

## Node 版本与 troubleshooting

### 官方支持范围

| Node 版本 | 状态 |
|---|---|
| **20 LTS** | 支持（CI 测试） |
| **22 LTS** | **推荐**（`.nvmrc` 默认值，CI 测试） |
| **24 Current** | 支持（CI 测试） |
| 18 及以下 | 不支持 |

`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 或跑测试时出现类似报错：

```text
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 版本下安装的，按以下步骤修复：

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

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

Windows PowerShell 等价命令：

```powershell
Remove-Item -Recurse -Force node_modules
npm install
```

### Windows 上 prebuild 下载失败

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

- [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)（勾选「使用 C++ 的桌面开发」）
- 或改用 WSL / Linux 环境开发

### MCP 配置建议

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

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

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

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

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

## 本地开发

```bash
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