Chengyu Coach

io.github.FlowerOfFirePublished by GitHub account FlowerOfFirev1.0.0Updated Oct 29, 2026

成语学习服务器：随机抽成语、查释义与出处，并按对话表现记录掌握程度

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & Memory

Overview

AI-generated overview

A local Chinese idiom (chengyu) study server that draws idioms, looks up meanings and origins, and tracks mastery in a local SQLite database.

What you can do
  • Draw random idioms, preferring ones never drawn before and skipping recently drawn or mastered entries
  • Look up an idiom's meaning, origin, classical example, draw count, status and notes
  • Search the built-in dictionary by keyword, pinyin or pinyin initials
  • Update mastery status (learning, reviewing, mastered) and add or clear free-form notes
  • Show overall progress counts and recent draws, and read entries or statistics as resources
  • Provide teaching and oral-quiz prompt templates for the client model to run
When to use it
Useful for daily Chinese idiom study with any MCP client: the assistant picks a few idioms, explains and quizzes them, and records how well the learner did. Suited to learners who want spaced, progress-tracked vocabulary practice rather than a fixed test set.
Requirements
Runs locally over stdio as a Python package (pip install or uvx). No account, API key or network access needed. Progress is stored by default at ~/.chengyu-coach/idiom_progress.db, and the CHENGYU_COACH_DB environment variable can point it elsewhere.
Before you install
The assistant writes mastery status and notes into the local database on its own judgment, and reset_word clears a word's learning record, so progress can be lost or mislabeled. Data stays on the machine and is not uploaded.

Installation

In SourceWeft

  1. Open Chengyu Coach in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

chengyu-coach-mcp

成语学习 MCP 服务器（Python，mcp SDK v2 的 MCPServer，stdio 传输）。内置 3303 条常用成语，学习进度存在本地 SQLite，让任意 MCP 客户端（Qoder / Claude Desktop / Cursor 等）帮你每天抽几个成语学，并根据聊天表现自动记录掌握程度。

  • 抽词：优先抽没抽过的；一轮抽完后按"抽得最少 + 最久没抽"轮转；默认跳过最近 20 条和已掌握的
  • 查询：每个成语抽中了几次、当前状态、备注
  • 记录：掌握状态 + 每词自由备注，由 AI 根据对话自行判断写入
  • 不内置测验卷：考不考、怎么考由客户端 AI 决定，服务端只负责抽词和记录

掌握状态：learning（还不熟）→ reviewing（基本会但不稳）→ mastered（能熟练解释和造句）。

安装

bash
pip install chengyu-coach-mcp        # 发布到 PyPI 后# 或使用 uvuvx chengyu-coach-mcp

从源码安装：

bash
git clone <repo-url> chengyu-coach-mcpcd chengyu-coach-mcppython -m venv .venv.venv/Scripts/pip install -e .        # Windows；macOS/Linux 用 .venv/bin/pip

接入 MCP 客户端

已安装到环境后，在客户端配置里加：

json
{  "mcpServers": {    "chengyu-coach": {      "command": "uvx",      "args": ["chengyu-coach-mcp"]    }  }}

从源码运行时（pip install -e . 之后），用解释器直接启动模块：

json
{  "mcpServers": {    "chengyu-coach": {      "command": "<项目路径>/.venv/Scripts/python.exe",      "args": ["-m", "chengyu_coach_mcp.server"]    }  }}

调试可用官方 MCP Inspector：

bash
npx @modelcontextprotocol/inspector uvx chengyu-coach-mcp

提供的能力

类型名称说明
Tooldraw_idiom随机抽成语（未抽过优先，可配数量/是否含已掌握）
Toolidiom_detail查词：释义、出处、古例 + 学习进度 + 备注
Toolsearch_idiom按关键词/拼音/拼音缩写搜词库
Toolupdate_statusAI 根据对话表现更新掌握状态（learning/reviewing/mastered）
Tooladd_note写/清备注
Toolprogress总进度：各状态数量、有备注数、最近抽取
Toolreset_word清空某词学习记录（destructive）
Resourcechengyu://{word}读取词库词条（JSON）
Resourcechengyu://stats学习进度统计（JSON）
Promptlearn_idiom教学提示词（讲解 + 双场景造句）
Promptquiz_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抽中次数
statuslearning / reviewing / mastered（由 AI 判断写入）
note自由备注
first_drawn / last_drawn首次/最近抽取时间

开发

bash
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 会校验四处版本号一致后自动构建上传：

bash
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。

Source: README.md at commit 3d410e1

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.0LatestOct 29, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts