chengyu-coach-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@chengyu-coach-mcp 抽三个成语考考我,答完记得更新我的掌握进度"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
chengyu-coach-mcp
成语学习 MCP 服务器(Python,mcp SDK v2 的 MCPServer,stdio 传输)。内置 3303 条常用成语,学习进度存在本地 SQLite,让任意 MCP 客户端(Qoder / Claude Desktop / Cursor 等)帮你每天抽几个成语学,并根据聊天表现自动记录掌握程度。
抽词:优先抽没抽过的;一轮抽完后按"抽得最少 + 最久没抽"轮转;默认跳过最近 20 条和已掌握的
查询:每个成语抽中了几次、当前状态、备注
记录:掌握状态 + 每词自由备注,由 AI 根据对话自行判断写入
不内置测验卷:考不考、怎么考由客户端 AI 决定,服务端只负责抽词和记录
掌握状态:learning(还不熟)→ reviewing(基本会但不稳)→ mastered(能熟练解释和造句)。
安装
pip install chengyu-coach-mcp # 发布到 PyPI 后
# 或使用 uv
uvx chengyu-coach-mcp从源码安装:
git clone <repo-url> chengyu-coach-mcp
cd chengyu-coach-mcp
python -m venv .venv
.venv/Scripts/pip install -e . # Windows;macOS/Linux 用 .venv/bin/pipRelated MCP server: mcp-server-maimemo
接入 MCP 客户端
已安装到环境后,在客户端配置里加:
{
"mcpServers": {
"chengyu-coach": {
"command": "uvx",
"args": ["chengyu-coach-mcp"]
}
}
}从源码运行时(pip install -e . 之后),用解释器直接启动模块:
{
"mcpServers": {
"chengyu-coach": {
"command": "<项目路径>/.venv/Scripts/python.exe",
"args": ["-m", "chengyu_coach_mcp.server"]
}
}
}调试可用官方 MCP Inspector:
npx @modelcontextprotocol/inspector uvx chengyu-coach-mcp提供的能力
类型 | 名称 | 说明 |
Tool |
| 随机抽成语(未抽过优先,可配数量/是否含已掌握) |
Tool |
| 查词:释义、出处、古例 + 学习进度 + 备注 |
Tool |
| 按关键词/拼音/拼音缩写搜词库 |
Tool |
| AI 根据对话表现更新掌握状态(learning/reviewing/mastered) |
Tool |
| 写/清备注 |
Tool |
| 总进度:各状态数量、有备注数、最近抽取 |
Tool |
| 清空某词学习记录(destructive) |
Resource |
| 读取词库词条(JSON) |
Resource |
| 学习进度统计(JSON) |
Prompt |
| 教学提示词(讲解 + 双场景造句) |
Prompt |
| 口头考问流程提示词(抽词→作答→讲评→记录状态) |
造句和出题都不需要服务端:抽题/查词结果已带释义、出处、古文例句,客户端大模型据此讲解、造句、提问,并把判断结果写回 update_status / add_note。
数据与隐私
学习记录默认写入
~/.chengyu-coach/idiom_progress.db,可用环境变量CHENGYU_COACH_DB指定其他路径数据只存在本机,不联网、不上传
词库随包分发,只读;替换
src/chengyu_coach_mcp/data/chengyu_common.json即可换词库(数组,每条需含word/pinyin/explanation/derivation/example/id)
user_word 表结构:
字段 | 说明 |
| 成语原文(主键) |
| 抽中次数 |
| learning / reviewing / mastered(由 AI 判断写入) |
| 自由备注 |
| 首次/最近抽取时间 |
开发
python -m venv .venv
.venv/Scripts/pip install -e .
.venv/Scripts/python tests/smoke_test.py # 端到端冒烟测试(自动使用临时数据库)项目结构:
chengyu-coach-mcp/
├── src/chengyu_coach_mcp/
│ ├── __init__.py # 版本号
│ ├── server.py # 词库加载 + SQLite + 全部工具/资源/提示词
│ └── data/chengyu_common.json # 常用成语词库(3303 条)
├── tests/smoke_test.py # stdio 端到端测试
├── .github/workflows/ci.yml # Linux/Windows × Python 3.10/3.12
├── .github/workflows/release.yml # 推 v* 标签自动发布到 PyPI(OIDC)
├── server.json # 官方 MCP Registry 元数据
├── pyproject.toml
├── LICENSE # MIT(代码)
├── THIRD_PARTY_NOTICES.md # 词库来源与许可
└── CHANGELOG.md发布新版本时同步改三处:pyproject.toml 的 version、src/chengyu_coach_mcp/__init__.py 的 __version__、CHANGELOG.md;server.json 里的 version 与 packages[0].version 也要跟上。改完打标签并推送,release.yml 会校验四处版本号一致后自动构建上传:
git tag -a v1.0.1 -m "chengyu-coach-mcp v1.0.1"
git push origin main --tagsREADME 顶部那行 <!-- mcp-name: io.github.FlowerOfFire/chengyu-coach-mcp --> 是给官方 MCP Registry 验证包所有权用的,发布到 PyPI 的版本里必须带着它,删掉会导致 mcp-publisher publish 失败。
数据来源与许可
代码:MIT
成语词条:chinese-xinhua(MIT)
词频数据:JioNLP(Apache-2.0)
Available Tools
7 toolsadd_noteA
给某个成语写备注(自由文本,如易错点、使用场景),会覆盖原备注。
Args: word: 成语原文 note: 备注内容;传空字符串则清除备注
Inputs: note (required), word (required). Returns: result
draw_idiomA
随机抽成语学习。优先抽没抽过的;都抽过一轮后,抽得最少且最久没抽的优先。默认跳过最近 20 条和已掌握的。
Args: count: 抽几个(1~10) include_mastered: 是否把已掌握的也放回抽奖池
Inputs: count, include_mastered. Returns: result
idiom_detailARead-only
查一个成语的释义、出处、古文例句,以及学习进度(抽中次数、状态、备注)。
Args: word: 成语原文,如 守株待兔
Inputs: word (required). Returns: result
progressARead-only
查看整体学习进度:接触了几个、各状态数量、有备注的、最近抽的 10 个。
Inputs: no named parameters. Returns: result
reset_wordBRead-onlyDestructive
清空某个成语的学习记录(抽中次数、状态、备注),词库本身不受影响。
Args: word: 成语原文
Inputs: word (required). Returns: result
search_idiomARead-only
按关键词搜成语(匹配成语、拼音或释义),并附各自的抽中次数。
Args: keyword: 关键词,中文或拼音缩写(如 szdt) limit: 最多返回几条(1~20)
Inputs: keyword (required), limit. Returns: result
update_statusA
根据对话中用户的实际表现,更新成语的掌握状态。由 AI 自行判断调用,服务端不做判分。
Args: word: 成语原文 status: learning=还不熟/答错/卡壳;reviewing=大致理解但不够稳;mastered=能准确解释并举一反三
Inputs: word (required), status (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool maps to a distinct action: random draw, single-word lookup, keyword search, note writing, status update, aggregate stats, and reset. The main overlap is between idiom_detail and search_idiom when a keyword is an exact idiom, but descriptions clarify that one returns full detail plus progress while the other returns a list with draw counts.
All names use snake_case, which is consistent and readable. Most follow a verb_noun pattern (draw_idiom, add_note, search_idiom, update_status, reset_word), with minor deviations like the noun-phrase idiom_detail and the bare noun progress.
Seven tools is well-scoped for a flashcard-style learning server, with one tool per core operation and no redundant surface area.
The lifecycle is well covered: draw, inspect, search, annotate, update mastery, view aggregate progress, and reset. Minor gaps exist—no way to list or filter idioms by status/note, no batch status update, and no browsing of the full corpus—but workarounds via search and progress exist.
Maintenance
Related MCP Connectors
MCP server for Chinese idioms (chengyu): lookup by word, pinyin or meaning with explanation and
MCP server for Chinese dictionary lookup: character definitions, pinyin, stroke order and word
MCP server for classical Chinese poetry: search poems by title, author, dynasty or verse, with full
Authoritative JLPT-graded Japanese dataset (kanji, vocab, grammar, history) via MCP and REST.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables management of Eudic dictionary wordbooks, including categories and words, directly from MCP-compatible clients like Claude Desktop.MIT
- AlicenseNot gradedqualityDmaintenanceExposes the Maimemo (墨墨背单词) Open API as MCP tools, enabling AI assistants to look up words, manage mnemonics and study plans, and maintain cloud notepads.1MIT
- AlicenseBqualityBmaintenanceEnables MCP-compatible AI clients to act as a personal exam-prep tutor for Chinese postgraduate entrance exams, with a local knowledge base, spaced-repetition review scheduling, worksheet generation and delivery (print/PDF/HTML/text), and learning analytics—all with zero third-party dependencies and data staying local.142MIT
- AlicenseCqualityCmaintenanceEnables users to connect their Maimemo account through a local MCP to query vocabulary, manage cloud wordbooks and learning materials, review study progress, and perform study actions via natural language.251MIT