Anki课程导师MCP服务器
人工智能驱动的学习系统，将Anki的间隔重复与通过聊天界面进行的人工智能驱动辅导相结合。
   
✨ 特性
- 🎓 基于聊天的学习 -通过MCP实现自然对话界面
- 🤖 AI解释 -对错误答案的上下文解释
- ✅ 用户评论系统 -确认或覆盖自动答案评估
- 📊 进度跟踪 -详细的统计数据和学习分析
- 🔄 Anki调度器集成 -直接向Anki的间隔重复系统提交评论
- 🎯 灵活的模式 -解释模式（带AI解释）或测试模式（仅评估）
- 🔌 11 MCP工具 -通过聊天界面完成学习工作流程
- 📝 多种卡类型 -基础、完形填空、多选（MC）、单选（SC）和KPRIM
- 🎨 灵活的答案格式 -KPRIM问题接受R/F、T/F、Y/N或1/0
先决条件
- Anki 已安装并正在运行
- AnkiConnect 已安装附加组件
- Python 3.13+
- 紫外线 用于包管理
安装
# Clone the repository
git clone
cd anki-course-tutor-mcp-server
# Install with uv (recommended)
uv sync
# Or with pip
pip install -e ".[dev]"Anki设置
- 安装 Anki
- 安装 AnkiConnect插件:
- 打开安基→ 工具→ 附加组件→ 获取扩展 - 输入代码： 2055492159 - 重新启动Anki
- 使用导师时，让Anki在后台运行
配置
编辑 config.yaml 自定义：
Anki连接和调度器
anki:
connect_url: "http://localhost:8765" # AnkiConnect URL
connect_timeout: 30 # Connection timeout (seconds)
retry_attempts: 3 # Number of retry attempts
use_anki_scheduler: true # Enable Anki scheduler integration调度器集成：
- 当
use_anki_scheduler: true，评论提交给Anki的原生间隔重复调度程序 - 卡片将出现在Anki中，并根据您的答案更新到期日期
- 简化地图绘制：正确=4（简单），不正确=1（再次）
- 需要使用AnkiConnect运行Anki Desktop
- 吃起来
false仅用于本地模式（无Anki调度程序更新）
要求：
- Anki Desktop必须正在运行
- AnkiConnect插件已安装并启用
- 卡必须具有Anki的数字ID
其他设置
- 导师个性和权重 -控制正常/海盗旋转
- 学习模式 -解释（用AI）或测试（仅评估）
- 评价行为 -区分大小写，空格处理
- 存储路径 -会话和进度数据位置
使用Claude Desktop
添加到您的 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：
{
"mcpServers": {
"anki-course-tutor": {
"command": "uv",
"args": [
"--directory",
"/full/path/to/anki-course-tutor-mcp-server",
"run",
"anki-course-tutor"
]
}
}
}重新启动Claude Desktop以加载MCP服务器。
💬 用法示例
开始会话
You: List my Anki decks
AI: I found these decks:
1. Spanish Vocabulary (150 cards)
2. Python Programming (87 cards)
You: Start a learning session with Spanish Vocabulary in EXPLAIN mode
AI: ✓ Created session abc-123 with 150 cards
Ready to begin! Type "next card" to start.复习学习
You: Next card
AI: 📝 Card 1/150
Question: ¿Cómo estás?
You: How are you?
AI: 🤔 I think this is CORRECT!
Expected: "How are you?" or "How do you do?"
Do you agree? (yes/no)
You: yes
AI: ✅ Correct! Progress: 1/150 cards completed获取解释（EXPLAIN模式）
You: What hour is it?
AI: 🤔 I think this is INCORRECT.
Expected: "What time is it?"
Do you agree? (yes/no)
You: yes
AI: Let me explain:
"¿Qué hora es?" translates to "What time is it?" in English.
While "hour" and "time" are related, we use "What time" as the
standard expression. Think of "time" as the specific point on
the clock, while "hour" is more about duration.格式灵活的KPRIM问题
You: Next card
AI: 📝 Card 5/150
Question: Welche Aussagen über Conditional Parameterization sind korrekt?
Options:
Q_1: Sie ist die graphische Darstellung von P(G|I)
Q_2: Sie verwendet bedingte Wahrscheinlichkeitstabellen
Q_3: Sie ist nur für diskrete Variablen definiert
Q_4: Sie ermöglicht effiziente Inferenz in Bayesianischen Netzen
Q_5: Sie ersetzt die Chain Rule vollständig
Hint: Sources: Folie 5 | Extra: Conditional Parameterization ist
die graphische Darstellung von P(G|I)
You: RRFRF
AI: You answered: 'RRFRF'
Correct answer: '1 1 0 1 0'
Was your answer correct? (yes/no)
You: yes
AI: ✅ Correct! Progress: 5/150 cards completed支持的KPRIM应答格式：
- R/F （德语）：
RRFRF,R,R,F,R,F,R R F R F - T/F （中文）：
TTFTT,T,T,F,T,T,T T F T T - 是/否:
YYNYN,Y,Y,N,Y,N,Y Y N Y N - 1/0 （数字）：
11010,1,1,0,1,0,1 1 0 1 0
所有格式都不区分大小写，也不区分分隔符。
## 🏗️ Architecture
### State Machine
未启动→ 出示卡片→ 唤醒应答 ↓ 评价 ↓ 觉醒_回顾 ↙ ↘ （正确）（不正确） ↓ ↓ 唤醒应答← 解释 ↓ 会话_完成
### MCP Tools
| Tool | Description |
|------|-------------|
| `list_decks` | List all available Anki decks |
| `start_session` | Create new learning session |
| `resume_session` | Resume paused session |
| `get_next_card` | Present next card question |
| `submit_answer` | Submit answer for evaluation |
| `confirm_evaluation` | Confirm/override evaluation |
| `get_explanation` | Get AI explanation (EXPLAIN mode) |
| `get_session_stats` | Get session statistics |
| `end_session` | Complete and save session |
## Configuration
Edit `config.yaml` to customize settings:
anki: connect_url: "http://localhost:8765" connect_timeout: 10
tutor: personalities: - name: "normal" ratio: 3 - name: "pirate" ratio: 1 modes: explain: max_sentences: 5
learning: simple_srs: retry_incorrect: true evaluation: case_sensitive: false
## 发展
Run tests (102 tests, 74% coverage)
uv run pytest
Run with coverage report
uv run pytest --cov=src --cov-report=html
Lint and format
ruff check src/ tests/ ruff format src/ tests/
Type checking
ruff check --select=F,I,B,C4,UP
### 项目结构
anki-course-tutor-mcp-server/ ├── src/anki_course_tutor/ │ ├── mcp_server.py # FastMCP tools and resources │ ├── learning_engine.py # State machine and evaluation │ ├── session_manager.py # Session CRUD │ ├── progress_tracker.py # Statistics and persistence │ ├── scheduler.py # Card scheduling │ ├── ai_tutor.py # AI explanations │ └── anki_client.py # Anki integration ├── tests/ # 100 tests ├── docs/ # Documentation │ └── MANUAL_TESTING.md # Testing guide └── data/ # Sessions and progress (gitignored)
## 🐛 故障排除
### AnkiConnect问题
**“AnkiConnect不可用”**
- 确保Anki Desktop正在运行
- 验证是否安装了AnkiConnect插件（工具→ 附加组件）
- 测试连接： `curl http://localhost:8765`
- 检查AnkiConnect配置是否允许本地连接
**“向Anki提交评论失败”**
- Anki Desktop必须在学习期间运行
- 检查 `use_anki_scheduler: true` 在 `config.yaml`
- 验证卡ID是否为数字（从Anki导入）
- 在Anki中查看AnkiConnect日志（工具→ 附加组件→ AnkiConnect→ 查看文件）
### 牌组和卡片问题
**“未找到甲板”**
- 检查甲板名称是否准确（区分大小写）
- 验证卡片组是否包含Anki中的卡片
- 刷新Anki牌组列表
- 尝试先列出套牌以查看可用名称
**“卡ID无效”**
- 必须使用数字ID从Anki导入卡
- 无法使用带有字符串ID的手动创建的卡进行调度程序集成
- 集 `use_anki_scheduler: false` 仅用于本地模式，不进行Anki更新
看 [docs/MANUAL_TESTING.md](docs/MANUAL_TESTING.md) 了解详细的故障排除。
## 🤝 贡献
看 [贡献.md](CONTRIBUTING.md) 发展指南。
要点：
- 遵循褶皱格式
- 添加新功能测试（目标：80%覆盖率）
- 更新OpenSpec提案以进行重大更改
- 在任何地方使用类型提示
## 许可证
Apache许可证2.0-请参阅 [许可证](LICENSE) 文件以获取详细信息。
版权所有2025 Michael Krech
## 状态
✅ **MVP完成** -所有核心功能均已实现，102项测试通过（覆盖率74%）