chinese-nlp-mcp

chinese-nlp-mcp

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

中国語 NLP 機能を備えた MCP サーバー：分かち書き、キーワード抽出、ピンイン変換、カスタム機密語検出。 ローカルの stdio で実行され、推論はすべてプロセス内で完了します。

📝 チュートリアル: AI エージェントに中国語 NLP を 5 分で追加する方法

特長

• 完全ローカルでの推論 — license key を設定していない場合、ネットワークリクエストもテレメトリーもなく、テキストがマシンの外に出ることはありません
• stdio transport — ローカルプロセス間通信を使用し、ポートは一切開きません
• クリーンなプロトコル — ログはすべて stderr に出力され、stdout の JSON-RPC ストリームを汚染しません

環境要件

Python 3.10 以降。

インストール

方法 1：uvx でワンクリック実行（推奨、インストール不要）

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 を使用します）

方法 2：pip でインストール

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

方法 3：ソースからインストール（代替手段、開発用）

git clone https://github.com/leonmch-byte/chinese-nlp-mcp
cd chinese-nlp-mcp

# Windows (Git Bash)
python -m venv .venv
./.venv/Scripts/python.exe -m pip install -r requirements.txt

# macOS / Linux
python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt

クライアントの接続

Python 環境を気にせずに済むため、uvx の使用をおすすめします。

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

pip でインストールした場合（方法 2）：

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

ソースからインストールした場合（方法 3）：

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

VS Code では servers キーを、Claude Desktop / Cursor では mcpServers キーを使用します。

ツール

ツール	シグネチャ	説明
hello_world	() -> str	ヘルスチェック。Hello from Chinese NLP MCP を返します
segment_chinese	(text: str, mode: str = "default") -> list[str]	中国語の分かち書き。mode は default / search / index に対応しています
convert_pinyin	(text: str, style: str = "tone", separator: str = " ") -> str	ピンイン変換。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} がそのまま返されます。 コンテンツ安全性のポリシーは利用者自身が管理する必要があり、このツールがあらかじめ設定することはありません。

知っておくべき動作の詳細

これらは戻り値の解析方法に直接関わるため、ここに記載しています。

detect_sensitive_words — 重複する一致はすべて返します

重複を除去したり、最長一致／最短一致を優先して絞り込んだりすることはありません。呼び出し元は自身の単語リストの管理者であり、 「何に一致したか」のうち何が重要かを最もよく把握しています。すべての一致を受け取った後、必要に応じて index を使って絞り込んだり集約したりできます。

例：text="中华人民共和国", words=["中国人民","人民"] → 2 件の一致を返し、 index はそれぞれ 0 と 2 になります。index は文字インデックスです（中国語は 1 文字を 1 と数え、バイト単位ではありません）。

extract_keywords — weight は正規化されていない TF-IDF の生スコアです

通常の値域は 0 ～ 6 で、1.0 を超えることがあります（例：「天安门广场」→ 1.6316）。 これは現在のコーパスにおける単語の重要度を表すものであり、確率やパーセンテージではありません。

戻り値はすでに重みの降順で並んでいます。topN が抽出可能な単語数を超える場合は、すべての単語を返し、エラーにはなりません。 中国語と英語が混在するテキストでは、英単語も独立したトークンとして保持され、計算に含まれます（フィルターされません）。 （例：Python 编程语言很强大 → Python が抽出され、weight は 3.98）。

convert_pinyin — tone2 の数字は母音の後に付きます

zhong → zho1ng であり、zhong1 ではありません。これは pypinyin で定められている命名規則です。 style に指定できるのは上記の 4 つの値のみで、それ以外を渡すとエラーになります（基盤ライブラリは本来、エラーを出さずに別の形式へフォールバックしますが、このプロジェクトでは「一見正しそうでも、求めていた結果とは異なる」事態を避けるため、入口で拒否します）。

segment_chinese — index と search の動作は同じです

jieba には独立した index モードがないため、このプロジェクトでは index を検索モードに割り当てています。 どちらのモードも位置情報は返さず、戻り値は一律 list[str] です。

戻り値の読み取り方

dict を返すツール（detect_sensitive_words）は、fastmcp によって structuredContent に直接展開され、result のラッパー層は追加されません。 list / str を返すツールは、structuredContent.result に格納されます。

例：値は structuredContent.matches と structuredContent.clean から取得します。 structuredContent.result.matches ではありません。

エラー処理

無効なパラメーターでは ValueError が、内部エラーでは RuntimeError が発生します。 いずれも fastmcp によって isError=true に変換され、ツールのシグネチャはシンプルに保たれます。

無料プランの 1 日あたりの上限（v0.2.0 以降）

すべてのツールを無料で使用できますが、1 日あたりの利用回数に上限があります（UTC 00:00 にリセット）。

ツール	1 日あたりの上限
hello_world	無制限（ヘルスチェックは常に許可されます）
segment_chinese	500
convert_pinyin	300
extract_keywords	100
detect_sensitive_words	200

1 回あたりの入力上限：テキスト 20,000 文字、カスタム単語リスト 1,000 件、topN は最大 50。

上限に達すると、そのツールは isError: true を返し、現在の制限、リセット時刻、Pro の特典、アップグレードリンクを提示します。hello_world は常に影響を受けないため、クライアントがサーバーの障害と誤認することはありません。

Pro License（v0.3.0 以降）

export CHINESE_NLP_LICENSE_KEY=<你的 key>   # Windows: $env:CHINESE_NLP_LICENSE_KEY="..."

項目	値
検証頻度	起動時に 1 回検証し、結果を 24 時間キャッシュします
オフライン時の猶予期間	7 日間（前回の検証成功から 7 日以内にネットワーク障害が発生した場合、Pro を維持します）
タイムアウト	8 秒、再試行なし
ローカル保存	デフォルトでは平文の key を保存しません

環境変数を毎回設定する手間を省きたい場合は、明示的に同意したうえで key をローカルに保存できます （アクセス権限 0600 + HMAC 署名）。

export CHINESE_NLP_STORE_KEY=1

診断には CHINESE_NLP_LICENSE_DEBUG=1 を使用します（tier とキャッシュの状態を stderr に出力します）。 自分でロックを解除するには CHINESE_NLP_LICENSE_RESET=1 を使用します（ローカルのキャッシュと認証情報を消去します）。

License が無効になっても通知されません：ポップアップは表示されず、ツールの戻り値の構造も変わりません。 無料プランの利用回数上限に戻るだけです（従来と同じ上限超過メッセージが表示されます）。

1 日あたりの利用回数は、ローカルの状態ファイルに保存されます。

• 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 ドルの買い切り、サブスクリプションではありません）

プライバシー

ライセンスキーなしの場合： 完全にオフラインです。ネットワークへの接続もテレメトリーもありません。 テキストがマシンの外部に送信されることはありません。

Pro ライセンスキーがある場合： 起動時に Gumroad でキーを一度検証し、24 時間キャッシュします。送信されるのは product_id と license_key のみです。 テキストの内容、使用統計、マシン識別子は送信されません。

CHINESE_NLP_LICENSE_KEY を設定しなければ、検証を完全に無効にできます。

ツール呼び出し自体は、どちらの場合も完全にオフラインです。ネットワーク要求が発生するのはサーバー起動時のみで、 ライセンスキーが設定されている場合に限られます。頻度は 24 時間に最大 1 回です。

ローカルに保存されるのはライセンスキーの SHA-256 ダイジェスト（先頭 16 桁の 16 進数）のみで、 平文は保存されません。キャッシュ、ログ、エラーメッセージに平文のキー、メールアドレス、IP アドレスは含まれません。

このプロジェクトは MIT ライセンスのオープンソースローカルソフトウェアであり、DRM はありません。 日次カウントは改ざん耐性（tamper-resistant）を備えていますが、改ざん不可能（tamper-proof）ではありません。 強い意志を持つ人なら、ソースコードのレベルであらゆるローカルの仕組みを回避できます。 私たちが販売するのは便利さ（バッチ API、長文、カスタム辞書）であり、ロックではありません。

開発

受け入れ方法、テスト規約、実装レイヤーでの落とし穴については DEVELOPMENT.md をご覧ください。

ライセンス

MIT