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 自己不会调用任何模型。

Related MCP server: Anki Card Manager (acm)

Windows 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 前应按官方迁移指南修改并重新验证。

初始化数据库

python -m japanese_learning_mcp.init_db

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

$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 客户端配置提交到仓库。

测试与静态检查

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

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

启动 MCP Server

python -m japanese_learning_mcp.server

也可在安装后运行：

japanese-learning-mcp

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

MCP 客户端配置

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

{
  "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，适合客户端 稳定解析。

复习规则

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

规则集中在 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 验证是：

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。