# Japanese Learning Memory MCP

一个可本地运行的个人日语学习知识库 MCP Server。它不是普通词典，而是让 ChatGPT、
Codex 或其他 MCP 客户端维护你的知识点、易混关系、真实错误和多维掌握度。

第一版使用 Python 3.11+、官方 MCP Python SDK 稳定版、标准库 `sqlite3` 和 stdio
transport。数据只保存在本机，不调用第三方大模型 API。

## 能力概览

六个 MCP Tools：

- `search_items`：按表达、读音、中文/日文释义和笔记搜索，支持类型、状态、JLPT 筛选。
- `upsert_item`：按 `(normalized_expression, item_type)` 保守查重并新增或更新。
- `add_relation`：建立易混、相似、反义、搭配等关系。
- `record_mistake`：追加阅读、听力、口语、写作等真实错误。
- `get_due_reviews`：只读获取到期复习及尚未复习的 learning 项目。
- `submit_review`：保存复习历史、更新对应掌握度并安排下次复习。

四个 Resources：`japanese://profile`、`japanese://stats`、
`japanese://recent-mistakes`、`japanese://due-today`。

三个 Prompts：`review_today`、`analyze_confusion`、`finish_speaking_session`。
Prompts 只向 MCP 客户端提供工作流指导，Server 自己不会调用任何模型。

## Windows PowerShell 安装

```powershell
cd <PROJECT_ROOT>
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

若执行策略阻止激活虚拟环境，可以不激活，后续把 `python` 替换为
`.\.venv\Scripts\python.exe`。

官方 SDK 依赖固定为 `mcp>=1.27,<2`。项目创建时 v2 仍是 release candidate，
官方明确建议生产项目使用稳定 v1.x；升级到 v2 前应按官方迁移指南修改并重新验证。

## 初始化数据库

```powershell
python -m japanese_learning_mcp.init_db
```

初始化是幂等的；Server 启动时也会自动执行相同 migration，不会删除或重建已有数据。
默认数据库为项目中的 `data\japanese_learning.db`。可用环境变量覆盖：

```powershell
$env:JAPANESE_LEARNING_MCP_DB = "D:\JapaneseData\my-memory.db"
python -m japanese_learning_mcp.init_db
```

真实 `.db`、WAL 和 SHM 文件已被 `.gitignore` 排除。

## 隐私与版本控制

个人知识点、错误记录、复习历史和掌握度全部保存在本地 SQLite 数据库中，不属于项目
源码。仓库默认忽略 `data/` 中的数据库文件、`*.db-wal`、`*.db-shm`、虚拟环境和
`.env` 文件，因此公开源码不会公开个人学习数据。

提交代码前仍建议运行 `git status --ignored`，确认数据库和本机配置处于 ignored 状态。
请勿把包含真实绝对路径、访问令牌或其他隐私信息的 MCP 客户端配置提交到仓库。

## 测试与静态检查

```powershell
python -m pytest -q
python -m ruff check .
```

测试数据库全部位于 pytest 临时目录，不会污染正式数据。

## 启动 MCP Server

```powershell
python -m japanese_learning_mcp.server
```

也可在安装后运行：

```powershell
japanese-learning-mcp
```

stdio 协议占用 stdout，因此应用日志只写 stderr。不要在 Server 进程中添加 `print()`。

## MCP 客户端配置

将占位符替换为你机器上的绝对路径：

```json
{
  "mcpServers": {
    "japanese-learning-memory": {
      "command": "<PROJECT_ROOT>\\.venv\\Scripts\\python.exe",
      "args": ["-m", "japanese_learning_mcp.server"],
      "env": {
        "JAPANESE_LEARNING_MCP_DB": "<YOUR_DATA_DIRECTORY>\\japanese_learning.db"
      }
    }
  }
}
```

若接受默认数据位置，可以删除整个 `env` 字段。不同客户端的配置文件位置不同，但
`command`、`args` 和 `env` 的含义相同。

## 示例录入与查询流程

在 MCP 客户端中依次调用：

1. `search_items({"query":"見落とす","item_type":"vocabulary"})` 查重。
2. 若不存在，调用
   `upsert_item({"item_type":"vocabulary","expression":"見落とす","reading":"みおとす",
   "meaning_zh":"看漏、忽略","jlpt_level":"N1"})`。
3. 口语中想不起该词时，使用返回的 `item.id` 调用
   `record_mistake({"activity_type":"speaking","problem_type":"recognition_only",
   "item_id":"<ITEM_ID>","expected_answer":"見落とす"})`。
4. 调用 `get_due_reviews({"limit":20})` 获取首次或到期任务。
5. 作答后调用
   `submit_review({"item_id":"<ITEM_ID>","review_type":"speaking","score":2})`。

结构化返回包含 `action`、最终对象、掌握度和 ISO 8601 格式的 `next_due_at`，适合客户端
稳定解析。

## 复习规则

第一版使用透明的固定间隔：

| score | 含义 | 下次复习 |
|---:|---|---:|
| 0 | 完全不会 | 10 分钟 |
| 1 | 有印象但答错 | 1 天 |
| 2 | 提示后想起 | 3 天 |
| 3 | 正确但明显犹豫 | 7 天 |
| 4 | 快速正确 | 14 天 |
| 5 | 能主动、自然使用 | 30 天 |

规则集中在 `services/review_service.py`。单次复习只把对应维度朝该分数的目标值移动
25%；表现下降时以 35% 的保守权重下调。`mixed` 会更新全部五个维度。一次 score 5
不会直接变成完全掌握。

状态为 `learning` 且无 review 历史的知识点视为“立即可进行首次复习”。该策略不创建
隐式记录；`get_due_reviews` 始终是纯查询。已有历史的项目以最近一条 review 的
`next_due_at` 为准，并用日期和 UUID 保证稳定排序。

## 数据设计说明

- 每次连接开启 `PRAGMA foreign_keys = ON`。
- migration 版本记录在 `schema_migrations`，当前 schema 版本为 1。
- `normalized_expression` 仅执行首尾清理、NFKC Unicode 规范化、删除开头展示用
  `～/〜`（规范化后也识别 `~`）和连续空格合并，不做日语词形还原。
- 不因读音相同合并不同汉字词。
- `confusable_with`、`similar_to`、`opposite_to` 是对称关系：数据库只保存一行，
  两端 UUID 按字典序规范化；反向添加会返回已有关系。
- 第一版没有物理删除 Tool；请使用 `status="archived"` 归档。

## 手动验证

最简单的自动化 MCP 验证是：

```powershell
python -m pytest tests\test_mcp.py -q
```

该测试通过官方 SDK 的内存 transport 完成初始化握手，发现 6/4/3 项能力，并真实调用
`upsert_item`。也可启动 Server 后用 MCP Inspector 连接 stdio 命令进行交互检查。

## 当前边界

第一版不包含 Web 前端、Docker、第三方模型 API、语音识别、向量数据库、Anki 同步，
也不负责判断日语内容是否权威。`examples` 数据表已预留来源与验证状态，但首批六个
核心 Tools 尚未提供例句写入 Tool；LLM 生成内容未来接入时必须保持
`llm_generated + unverified`。