🚀 MCPY-CLI: 快速从 Python 文件构建 MCP 服务

🚀 MCPY-CLI：Python ファイルから MCP サーバーをすばやく構築

英語版

mcpy-cli へようこそ！このガイドでは、簡単な手順で独自の MCP（モデルコンテキストプロトコル）サービスを作成、実行、変換、デプロイする方法を紹介します。

mcpy-cli とは？

MCP サービスの開発を簡素化するために設計されたツールキットです。次のことができます。

• 📦 すばやくパッケージ化：1 つまたは複数の Python 関数やスクリプトを標準的な MCP サービスに変換します
• 🚀 ワンクリックでデプロイ：コマンドラインからサービスをすばやく起動または公開します
• 🔄 自動ルーティング：ファイル構造に基づいてサービスインターフェースを自動生成します
• 🌐 柔軟な設定：複数のトランスポートプロトコル、永続化、キャッシュに対応しています

🔥 クイックスタート

1. 動作環境：

Python >= 3.10 で、FastMCP がインストールされている必要があります。uv のインストールをおすすめします。

# 使用 pip 下载
pip install mcpy-cli

# 使用 uv (如已安装)
uv pip install mcpy-cli

# 使用 uv (未安装)
pip install uv
uv pip install mcpy-cli

2. MCP サービスの例

mcpy-cli example

3. MCP サービスの構築

# 假设在根目录下有一个 sample_tools.py 的文件
mcpy-cli run --source-path sample_tools.py

または、uv をインストールしている場合

uvx --from mcpy-cli mcpy-cli --source-path sample_tools.py run

サービスの起動後、テストページにアクセスします：http://localhost:8080/mcp-server/mcp

このページを開くには、MCP inspector の使用をおすすめします

📖 使用ガイド

🔬 コアツール：run と package

このプロジェクトでは、.py スクリプトを MCP サービスに変換するためのツールを 2 種類提供しています。ローカル実行ツール（run）とパッケージ化ツール（package）です。

1. ローカル実行

• mcpy-cli run コマンドを使用すると、複数の Python ファイルに含まれる関数を、指定したポートで動作する MCP サービスとしてローカルにデプロイできます
• 自動リロードに対応しており、開発やデバッグに適しています

2. パッケージ化

• mcpy-cli package コマンドを使用すると、指定したフォルダーを project という名前のフォルダーにパッケージ化できます
• サービス起動用のスクリプトとして start.sh を提供するため、デプロイや変更が簡単です

# 启动服务
mcpy-cli run --source-path /path/to/your/code --port 8080
# 或者使用 uvx
uvx mcpy-cli run --source-path /path/to/your/code --port 8080

# 打包服务（用于生产部署）
mcpy-cli package --source-path /path/to/your/code --package-name my-service
# 或者使用 uvx
uvx mcpy-cli package --source-path /path/to/your/code --package-name my-service

# 查看帮助
mcpy-cli --help
# 或者使用 uvx
uvx mcpy-cli --help

🛠️ 2 種類のアーキテクチャモード

このプロジェクトでは、異なる MCP サービスのアーキテクチャを 2 種類提供しています。具体的なニーズに応じて選択できます。

📋 Composed モード（合成モード）- デフォルト

仕組み：

• メインの FastMCP インスタンスを「ホスト」として作成します
• Python ファイルごとに独立した FastMCP サブインスタンスを作成します
• すべてのサブインスタンスをメインインスタンスにマウントし、プレフィックスと区切り文字で各ツールを区別します

使用例：

# 使用组合模式（默认）
mcpy-cli run --source-path ./my_tools --mode composed

# 访问地址：http://localhost:8080/mcp-server/mcp
# 工具调用：tool_file1_add, tool_file2_calculate 等

🔀 Routed モード（ルーティングモード）

仕組み：

• Python ファイルごとに独立した FastMCP インスタンスを作成します
• 各インスタンスに個別のルートパスを割り当てます
• ファイルのディレクトリ構造に基づいて、アクセスパスを自動生成します

使用例：

# 使用路由模式
mcpy-cli run --source-path ./my_tools --mode routed

# 访问地址：
# http://localhost:8080/math_tools - 数学工具模块
# http://localhost:8080/text_tools - 文本工具模块
# http://localhost:8080/data_tools - 数据工具模块

基本パラメーターの説明

パラメーター	説明	デフォルト値
--source-path	Python コードを含むファイルまたはディレクトリ	カレントディレクトリ
--port	サービスの待ち受けポート	8080
--host	サービスの待ち受けアドレス	127.0.0.1
--mcp-name	サービス名	自動生成
--mode	アーキテクチャモード (composed/routed)	composed
--legacy-sse	従来のSSEトランスポートを使用 (非推奨)	無効

🤝 クライアントでの使用

ローカル実行ツールでサービスを起動した後、次の方法で呼び出せます。

1. MCP Inspector

MCP Inspector を使用し、左上で【streamable-http】を選択して、生成されたサービス URL を入力します（デフォルトのアドレスは http://localhost:8080/mcp-server/mcp です）。

2. MCP 対応クライアントの使用

CherryStudio を例に説明します。

🧀 詳細設定

1. トランスポートプロトコルの選択

mcpy-cli は複数のトランスポートプロトコル設定に対応しています。

• デフォルトモード（Streamable HTTP）：より安定していて簡単なため、使用をおすすめします

  mcpy-cli run --source-path ./my_tools
  

• 従来のSSEモード：--legacy-sse で有効にします（非推奨。互換性のためにのみ使用してください）

  mcpy-cli run --source-path ./my_tools --legacy-sse
  

  ⚠️ 注意：従来のSSEモードは、一部のクラウド環境（Knative/Istio など）でパスの問題が発生することがあります。デフォルトの Streamable HTTP モードを使用することをおすすめします。

2. サービスの永続化

mcpy-cli はイベントストア（EventStore）を使用したサービスの永続化と状態復元に対応しています。この機能を有効にすると、サービスは JSON-RPC メッセージを保存し、サービスの中断や再起動後に特定のイベント時点から実行を再開できます。

• 実装方法：デフォルトでは SQLiteEventStore を使用し、イベントデータをローカルの SQLite データベースファイルに保存します。
• 有効化方法：サービスの起動時に --enable-event-store フラグを使用します。
• データベースのパス：--event-store-path パラメーターでイベントストアのデータベースファイルのパスを指定できます。指定しない場合、デフォルトは ./mcp_event_store.db です。

# 启用事件存储并指定数据库路径
mcpy-cli run --source-path ./my_tools --enable-event-store --event-store-path ./my_service_events.db

この機能は、長時間実行する MCP サービスや、セッション状態を維持する必要がある MCP サービスに特に役立ちます。

3. キャッシュ

パフォーマンスを向上させ、重複計算を減らすため、このツールはセッション単位のツール呼び出しキャッシュ（SessionToolCallCache）を提供しています。

• 仕組み：このキャッシュはメモリ内に保持され、特定のユーザーセッションにおけるツール呼び出しの結果を保存します。同じセッション内で同じツールを同じパラメーターで再度呼び出すと、ツール関数を再実行せずにキャッシュから結果を返せます。
• 適用シナリオ：このキャッシュは主に「ステートフル JSON レスポンスモード」（stateful JSON response mode）で有効になり、機能します。
• ライフサイクル：キャッシュの内容はユーザーセッションに紐付いており、セッションの終了または消去時に関連するキャッシュも消去されます。

この仕組みにより、セッション中に頻繁に呼び出される可能性があるツールの応答速度を最適化できます。

📚 その他のリソース

• 完全なドキュメント
• アーキテクチャ設計ガイド
• ベストプラクティス