Skip to main content
Glama

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/pip

Related 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

draw_idiom

随机抽成语(未抽过优先,可配数量/是否含已掌握)

Tool

idiom_detail

查词:释义、出处、古例 + 学习进度 + 备注

Tool

search_idiom

按关键词/拼音/拼音缩写搜词库

Tool

update_status

AI 根据对话表现更新掌握状态(learning/reviewing/mastered)

Tool

add_note

写/清备注

Tool

progress

总进度:各状态数量、有备注数、最近抽取

Tool

reset_word

清空某词学习记录(destructive)

Resource

chengyu://{word}

读取词库词条(JSON)

Resource

chengyu://stats

学习进度统计(JSON)

Prompt

learn_idiom

教学提示词(讲解 + 双场景造句)

Prompt

quiz_me

口头考问流程提示词(抽词→作答→讲评→记录状态)

造句和出题都不需要服务端:抽题/查词结果已带释义、出处、古文例句,客户端大模型据此讲解、造句、提问,并把判断结果写回 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 表结构:

字段

说明

word

成语原文(主键)

draw_count

抽中次数

status

learning / reviewing / mastered(由 AI 判断写入)

note

自由备注

first_drawn / last_drawn

首次/最近抽取时间

开发

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 --tags

README 顶部那行 <!-- mcp-name: io.github.FlowerOfFire/chengyu-coach-mcp --> 是给官方 MCP Registry 验证包所有权用的,发布到 PyPI 的版本里必须带着它,删掉会导致 mcp-publisher publish 失败。

数据来源与许可

详见 THIRD_PARTY_NOTICES.md。

Available Tools

7 tools
add_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_detailA
Read-only

查一个成语的释义、出处、古文例句,以及学习进度(抽中次数、状态、备注)。

Args: word: 成语原文,如 守株待兔

Inputs: word (required). Returns: result

progressA
Read-only

查看整体学习进度:接触了几个、各状态数量、有备注的、最近抽的 10 个。

Inputs: no named parameters. Returns: result

reset_wordB
Read-onlyDestructive

清空某个成语的学习记录(抽中次数、状态、备注),词库本身不受影响。

Args: word: 成语原文

Inputs: word (required). Returns: result

search_idiomA
Read-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

    A3.8/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    Seven tools is well-scoped for a flashcard-style learning server, with one tool per core operation and no redundant surface area.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables management of Eudic dictionary wordbooks, including categories and words, directly from MCP-compatible clients like Claude Desktop.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes the Maimemo (墨墨背单词) Open API as MCP tools, enabling AI assistants to look up words, manage mnemonics and study plans, and maintain cloud notepads.
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      14
      2
      MIT