Chinese Nlp Mcp

io.github.leonmch-bytev0.2.0更新於 Oct 11, 2026

Chinese NLP toolkit for MCP: segmentation, pinyin, keywords, sensitive words. Offline via stdio.

已驗證STDIO僅桌面AI & MLKnowledge & Memory

概覽

AI 產生的概覽

在本機離線執行的中文 NLP 伺服器，提供斷詞、拼音轉換、關鍵詞擷取，以及由呼叫方提供詞庫的敏感詞比對。

功能
透過 stdio 在本機執行，提供四個中文處理工具：segment_chinese（jieba 斷詞，支援 default、search、index 三種模式）、convert_pinyin（pypinyin 拼音轉換，支援 tone、tone2、initials、first_letter 四種風格）、extract_keywords（TF-IDF 關鍵詞擷取，回傳詞與權重）、detect_sensitive_words（Aho-Corasick 比對呼叫方傳入的詞庫）。另有 hello_world 作為健康檢查。所有推論都在本機完成，不會發出網路請求。
適用情境
適合需要處理中文文本的情境：把文本切成詞、轉成拼音、擷取關鍵詞，或依自備詞庫篩檢敏感詞，同時不希望把文本送到外部服務。
執行需求
需要 Python 3.13 以上版本，或使用 uv/uvx 執行器。可從 PyPI 安裝 chinese-nlp-mcp，也可用 uvx 直接執行，文件另提供原始碼安裝方式。未宣告任何帳號、API 金鑰或環境變數。僅在桌面用戶端上以本機 stdio 程序執行。
安裝前請注意
敏感詞工具不內建任何詞庫；傳入空清單或省略 words 參數等同於不檢測，結果會直接回報為乾淨，因此檢測效果完全取決於你提供的詞庫。免費層對各工具有每日呼叫上限（例如斷詞 500 次、關鍵詞擷取 100 次），超過上限會回傳錯誤並附上升級連結。用量計數保存在本機狀態檔案中。另有付費 Pro 版本。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Chinese Nlp Mcp，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

chinese-nlp-mcp

mcp-name: io.github.leonmch-byte/chinese-nlp-mcp

中文 NLP 能力的 MCP Server，面向海外开发者。本地 stdio 运行，纯离线推理。

特性

  • stdio transport — 本地进程通信，不开放任何端口
  • 纯本地 — 关闭 fastmcp 版本检查，启动零网络请求
  • 协议安全 — 日志一律写 stderr，绝不污染 stdout 的 JSON-RPC 流

环境要求

  • Python 3.13+
  • 依赖装在项目专用 venv，不污染系统 Python

安装

方式一：uvx 一键运行（推荐，无需安装）

bash
uvx chinese-nlp-mcp

需要先安装 uv：https://docs.astral.sh/uv/getting-started/installation/ （macOS/Linux 用 curl -LsSf https://astral.sh/uv/install.sh | sh， Windows 用 irm https://astral.sh/uv/install.ps1 | iex）

方式二：pip 安装

bash
pip install chinese-nlp-mcp# 安装后同样可用命令行启动chinese-nlp-mcp

方式三：从源码安装（备选，开发用）

bash
git clone https://github.com/leonmch-byte/chinese-nlp-mcpcd chinese-nlp-mcp
# Windows (Git Bash)python -m venv .venv./.venv/Scripts/python.exe -m pip install -r requirements.txt
# macOS / Linuxpython3 -m venv .venv./.venv/bin/python -m pip install -r requirements.txt

客户端接入

推荐用 uvx，无需关心 Python 环境：

json
{  "mcpServers": {    "chinese-nlp-mcp": {      "command": "uvx",      "args": ["chinese-nlp-mcp"]    }  }}

若用 pip 安装（方式二）：

json
{  "mcpServers": {    "chinese-nlp-mcp": {      "command": "chinese-nlp-mcp"    }  }}

若从源码安装（方式三）：

json
{  "mcpServers": {    "chinese-nlp-mcp": {      "command": "/absolute/path/to/chinese-nlp-mcp/.venv/Scripts/python.exe",      "args": ["/absolute/path/to/chinese-nlp-mcp/server.py"]    }  }}

工具

已实现工具

工具签名说明
hello_world() -> str健康检查，返回 Hello from Chinese NLP MCP
segment_chinese(text: str, mode: str = "default") -> list[str]jieba 分词，mode 支持 default / search / index
convert_pinyin(text: str, style: str = "tone", separator: str = " ") -> strpypinyin 拼音转换，style 支持 tone / tone2 / initials / first_letter
extract_keywords(text: str, topN: int = 10) -> list[dict]TF-IDF 关键词提取，返回 [{word, weight}]，按权重降序
detect_sensitive_words(text: str, words: list[str] | None = None) -> dict自定义敏感词检测，Aho-Corasick 自动机

🔴 detect_sensitive_words 红线（不可协商）

本工具不含任何内置词库，也不内置任何示例词。词库唯一来源是调用方传入的 words 参数。传 [] 或 None 等同于不检测，直接返回 {"matches": [], "clean": true}。 这是项目级设计红线：内容安全策略必须由使用者自己掌控，工具不得替他预设。

免费层每日配额（v0.2.0 起）

所有工具都可免费使用，但有每日次数上限（按 UTC 00:00 重置）：

工具每日上限
hello_world无限制（健康检查永不拦截）
segment_chinese500
convert_pinyin300
extract_keywords100
detect_sensitive_words200

单次输入上限：文本 20,000 字符、自定义词库 1,000 条、topN 最大 50。

达到上限时该工具返回 isError: true，并附带当前限制、重置时间、 Pro 权益与升级链接。hello_world 始终不受影响，避免客户端误判服务器故障。

🔒 完全离线：本版本不做任何 License Key 在线校验，不发起网络请求， 不发送任何数据。计数只保存在你本机的状态文件里。

  • Windows: %LOCALAPPDATA%\chinese-nlp-mcp\
  • macOS: ~/Library/Application Support/chinese-nlp-mcp/
  • Linux: $XDG_STATE_HOME/chinese-nlp-mcp/

需要更高额度与批量 API：https://wolfmanchao.gumroad.com/l/chinese-nlp-mcp-pro （$19 买断，非订阅）

重叠匹配策略：返回全部命中，不去重、不做最长/最短优先裁剪。 理由：调用方是自己词库的负责人，最清楚"命中什么"才是关心的信号。 若工具替他裁剪（例如只留最长匹配），他既无法知道被裁掉的短词也命中了， 也无法对重叠区间做差异化处置。拿到全部命中后，调用方完全可以按 index 自行裁剪或聚合，而工具不做这个预设立场。

例：text="中华人民共和国", words=["中国人民","人民"] → 返回 2 条命中，index 分别为 0 和 2。

实现方案：pyahocorasick（实测 Windows + Python 3.13 有预编译 wheel， 无需本地编译；4813 词库 × 10 万字文本耗时 0.008 秒）。 index 是字符索引（中文按 1 字计，非字节索引）。

返回值读取方式：本工具返回 dict，fastmcp 会将其直接展开为 structuredContent，不额外加 result 包装层（这与返回 list/str 的 工具不同，后者会被包成 structuredContent.result）。 调用方应从 structuredContent.matches 与 structuredContent.clean 取值。

extract_keywords 说明：

  • 底层 jieba 的参数名是 topK（非 topN），且需 withWeight=True 才会返回权重。
  • weight 是 TF-IDF 原始分，未归一化，值域通常 0 ~ 6，可大于 1.0 （例："天安门广场" → 1.6316）。它表示该词在当前语料中的重要程度， 不是概率或百分比。
  • 返回顺序已按权重降序；topN 超过可提取词数时返回全部词，不报错。
  • 本工具是四个业务工具中唯一返回 list[dict] 的，属有意设计。
  • 中英混合文本中，英文单词会被 jieba 作为独立 token 保留并参与 TF-IDF 计算， 不会被过滤（例：Python 编程语言很强大 → 提取出 Python，weight 3.98）。

style 四种风格说明：实测 pypinyin 0.55.0 的 lazy_pinyin(text, style="bad") 不会报错，而是静默降级为 Style.NORMAL（带调拼音）。因此本工具在入口处 强制白名单校验，不把非法style 透传给底层库。

取值参考：tone → zhōng、tone2 → zho1ng、initials → zh、first_letter → z。

tone2 标注规则：遵循 pypinyin 原生命名规则，声调数字标注在元音后 （如 zho1ng），而非词尾（zhong1）。这是 pypinyin 的既有行为，非缺陷。

mode 三模式说明：jieba 0.42.1 顶层没有 cut_for_index， 且 tokenize(mode=...) 内部只区分 default 与"其他"，传 index 会 静默降级为 search。本项目显式将 index 映射到 cut_for_search， 行为与 search 一致，避免给调用方"index 是独立模式"的错觉。

search / index 下jieba 内部计算的 (word, start, end) 位置信息不返回， 返回值统一为 list[str]。

错误处理：参数非法抛 ValueError，内部失败抛 RuntimeError， 均由 fastmcp 转成 isError=true，工具签名保持纯净、不返回错误包装体。

测试规约（Day 3 锁定）：

  1. 反例必须同时断言 isError=true 且 错误文案包含预期片段。只看标志位会漏过 "底层库静默降级"类回归——错误可能被包装成别的异常，isError 照样为true。
  2. stdio 子进程的 stderr 必须接文件或 DEVNULL，绝不接 subprocess.PIPE。 fastmcp 报错时 rich 会打印几十 KB traceback，塞满管道会导致 server 侧写阻塞、 响应永远发不出（表现为假死/超时，而非真实崩溃）。
  3. 提交前必须用 git status 检查暂存区，确认不含本地临时文件； 禁止 git add -A 后直接 commit。本地取证脚本、stderr 日志等 必须先确认已被 .gitignore 覆盖。
  4. 库行为 / 协议行为必须实测，不能凭记忆写断言。 反例：写convert_pinyin 断言时曾以为 first_letter 是"整词取首字母"， 实测 pypinyin 是逐字处理 —— 中华 → z h（非 zh）， initials 同理为 zh h。断言按直觉写会全盘皆错，而项目实现是对的。 同类教训：FastMCP 4.1.0 对普通异常会加 Error calling tool 'x': 前缀， 只有 ToolError 分支输出纯净文案 —— 这也是靠 stdio 实测确认的。 任何第三方库或协议的返回值/异常语义，先跑一次最小实验验证，再写断言。

detect_sensitive_words 刻意不内置任何词库。仅接受调用方传入的 words， 返回 {matches: [{word, index}], clean: bool}。

开发

验收统一走 Inspector 手工验证：

bash
npx @modelcontextprotocol/inspector \  ./.venv/Scripts/python.exe server.py

浏览器打开提示的地址（默认 http://localhost:6274），在 Tools 面板即可看到并调用工具。

Day 2 状态

工具状态说明
segment_chinese✅ 已实现jieba 三模式（default / search / index），mode 白名单校验

路线图

  • Day 1 — 项目骨架 + hello_world + Inspector 验收
  • Day 2 — segment_chinese（jieba 三模式）
  • Day 3 — convert_pinyin（pypinyin 四 style）
  • Day 4 — extract_keywords（TF-IDF）
  • Day 5 — detect_sensitive_words（Aho-Corasick）

每个工具独立实现、独立验收、独立提交。

License

MIT

來源：README.md，提交 5a529f6

工具

0
工具後設資料尚未被收錄。

版本歷史

1
  1. v0.2.0最新Oct 11, 2026