Pixelle MCP

🚀 🎨 Pixelle MCP - オムニモーダルエージェントフレームワーク

✨ MCPプロトコルに基づくAIGCソリューションで、ComfyUIのワークフローをゼロコードでシームレスにMCPツールに変換し、LLMとComfyUIの統合を可能にします。

🚀 クイックスタート

📥 1. ソースコードのクローンとサービスの設定

📦 1.1 ソースコードのクローン

git clone https://github.com/AIDC-AI/Pixelle-MCP.git
cd Pixelle-MCP

⚙️ 1.2 サービスの設定

このプロジェクトは統一されたYAML設定方式を使用しています。

# 設定例ファイルのコピー
cp config.yml.example config.yml
# 必要に応じて設定項目を編集

📋 詳細な設定手順: 設定ファイルには、基本サービス、MCPサーバー、MCPクライアントの3つの主要なセクションが含まれています。各セクションの詳細な設定項目の説明は、に記載されています。

🔍 設定チェックリスト:

• ✅ config.yml.exampleをconfig.ymlにコピーしました。
• ✅ ComfyUIサービスのアドレスを設定しました（ComfyUIが実行中であることを確認）。
• ✅ 少なくとも1つのLLMモデル（OpenAIまたはOllama）を設定しました。
• ✅ ポート番号が他のサービスによって占有されていないことを確認しました（9001、9002、9003）。

🔧 2. MCPツールの追加（オプション）

この手順はオプションで、エージェントの機能にのみ影響します。現時点で必要ない場合はスキップできます。 mcp-server/workflowsディレクトリには、デフォルトで一般的なワークフローのセットが含まれています。次のコマンドを実行して、これらをmcp-serverにコピーします。サービスを起動すると、これらは自動的にLLMで使用するためのMCPツールに変換されます。

注意: コピーする前に、ComfyUIのキャンバスでワークフローをテストすることを強くお勧めします。これにより、後で円滑に実行できます。

cp -r mcp-server/workflows/* mcp-server/data/custom_workflows/

🚀 3. サービスの起動

🎯 3.1 Dockerで起動（推奨）

# すべてのサービスを起動
docker compose up -d

🛠️ 3.2 ワンクリックスクリプトで起動

uv環境が必要です。

Linux/macOSユーザー:

# すべてのサービスを起動（フォアグラウンド）
./run.sh

# または

# すべてのサービスを起動（バックグラウンド）
./run.sh start --daemon

Windowsユーザー: ルートディレクトリのrun.batスクリプトをダブルクリックするだけです。

🛠️ 3.3 手動でサービスを起動

uv環境が必要です。

基本サービス（mcp-base）の起動:

cd mcp-base
# 依存関係のインストール（初回実行または更新後のみ必要）
uv sync
# サービスの起動
uv run main.py

サーバー（mcp-server）の起動:

cd mcp-server
# 依存関係のインストール（初回実行または更新後のみ必要）
uv sync
# サービスの起動
uv run main.py

クライアント（mcp-client）の起動:

cd mcp-client
# 依存関係のインストール（初回実行または更新後のみ必要）
uv sync
# サービスの起動（開発モードでホットリロードする場合は: uv run chainlit run main.py -w --port 9003）
uv run main.py

🌐 4. サービスへのアクセス

起動後、サービスのアドレスは以下の通りです。

• クライアント: 🌐 http://localhost:9003 (Chainlit Web UI、デフォルトのユーザー名とパスワードは両方ともdevで、で変更できます)
• サーバー: 🗄️ http://localhost:9002/sse (MCPサーバー)
• 基本サービス: 🔧 http://localhost:9001/docs (ファイルストレージと基本API)

✨ 主な機能

• ✅ 🔄 全モーダル対応: TISV（テキスト、画像、音声、ビデオ）の全モーダル変換と生成をサポートします。
• ✅ 🧩 ComfyUIエコシステム: サーバー側はComfyUIに基づいて構築されており、オープンなComfyUIエコシステムのすべての機能を引き継いでいます。
• ✅ 🔧 ゼロコード開発: Workflow-as-MCP Toolソリューションを定義および実装し、ゼロコードでの開発と新しいMCPツールの動的な追加を可能にします。
• ✅ 🗄️ MCPサーバー: サーバーはMCPプロトコルに基づく機能を提供し、任意のMCPクライアント（Cursor、Claude Desktopなどを含むがこれらに限定されません）との統合をサポートします。
• ✅ 🌐 MCPクライアント: クライアントはChainlitフレームワークに基づいて開発されており、ChainlitのUIコントロールを引き継ぎ、より多くのMCPサーバーとの統合をサポートします。
• ✅ 🔄 柔軟なデプロイメント: サーバー側をMCPサーバーとして単独でデプロイするか、クライアント側をMCPクライアントとして単独でデプロイするか、または組み合わせてデプロイすることができます。
• ✅ ⚙️ 統一された設定: YAML設定方式を使用し、1つの設定ファイルですべてのサービスを管理します。

📦 プロジェクト構造

• mcp-base: 🔧 基本サービスで、ファイルストレージと共有サービス機能を提供します。
• mcp-client: 🌐 MCPクライアントで、Chainlitに基づいて構築されたWebインターフェースです。
• mcp-server: 🗄️ MCPサーバーで、さまざまなAIGCツールとサービスを提供します。

プロジェクト構造

💻 使用例

基本的な使用法

ComfyUIで画像のガウシアンブラー用のワークフローを構築し、MCPツールとして追加する例です。

# このセクションではコード例がないため、元の手順を説明します。
# 1. ComfyUIで画像のガウシアンブラー用のワークフローを構築します（[ここから取得](docs/i_blur_ui.json)）。
# 2. `LoadImage`ノードのタイトルを`$image.image!`に設定します。
# 3. ワークフローをAPI形式のファイルとしてエクスポートし、`i_blur.json`にリネームします。
# 4. エクスポートしたAPIワークフローファイルをコピーし、Webページに入力して、LLMにこのツールを追加させます。
# 5. 送信後、LLMがこのワークフローを自動的にMCPツールに変換します。
# 6. ページを更新し、任意の画像を送信して、LLMを介してガウシアンブラー処理を実行します。

高度な使用法

複雑なMCPツールを追加する例です。

# 手順は基本的な使用法と同じですが、ワークフロー部分が異なります。
# ワークフローをダウンロードします（[UI形式](docs/t2i_by_flux_turbo_ui.json)と[API形式](docs/t2i_by_flux_turbo.json)）。
# 以降の手順は基本的な使用法と同じです。

📚 ドキュメント

🛠️ 独自のMCPツールの追加

⚡ 1つのワークフロー = 1つのMCPツール

🎯 1. 最も簡単なMCPツールの追加

• 📝 ComfyUIで画像のガウシアンブラー用のワークフローを構築します（ここから取得）。次に、LoadImageノードのタイトルを$image.image!に設定します。
• 📤 これをAPI形式のファイルとしてエクスポートし、i_blur.jsonにリネームします。自分でエクスポートするか、事前にエクスポートされたバージョンを使用できます（ここから取得）。
• 📋 エクスポートしたAPIワークフローファイル（API形式である必要があります）をコピーし、Webページに入力して、LLMにこのツールを追加させます。
• ✨ 送信後、LLMがこのワークフローを自動的にMCPツールに変換します。
• 🎨 ページを更新し、任意の画像を送信して、LLMを介してガウシアンブラー処理を実行します。

🔌 2. 複雑なMCPツールの追加

手順は上記と同じですが、ワークフロー部分が異なります（ワークフローをダウンロード: UI形式とAPI形式）。

🔧 ComfyUIワークフローのカスタム仕様

🎨 ワークフロー形式

システムはComfyUIのワークフローをサポートしています。キャンバスでワークフローを設計し、API形式としてエクスポートします。ノードのタイトルに特殊な構文を使用して、パラメータと出力を定義します。

📝 パラメータ定義仕様

ComfyUIのキャンバスで、ノードのタイトルをダブルクリックして編集し、次のDSL構文を使用してパラメータを定義します。

$<param_name>.<field_name>[!][:<description>]

🔍 構文の説明:

• param_name: 生成されるMCPツール関数のパラメータ名
• field_name: ノード内の対応する入力フィールド
• !: このパラメータが必須であることを示します
• description: パラメータの説明

💡 例:

必須パラメータの例:

• LoadImageノードのタイトルを$image.image!:入力画像のURLに設定します。
• 意味: imageという名前の必須パラメータを作成し、ノードのimageフィールドにマッピングします。

オプションパラメータの例:

• EmptyLatentImageノードのタイトルを$width.width:画像の幅、デフォルト512に設定します。
• 意味: widthという名前のオプションパラメータを作成し、ノードのwidthフィールドにマッピングし、デフォルト値は512です。

🎯 型推論ルール

システムはノードフィールドの現在の値に基づいてパラメータの型を自動的に推論します。

• 🔢 int: 整数値（例: 512、1024）
• 📊 float: 浮動小数点数値（例: 1.5、3.14）
• ✅ bool: ブール値（例: true、false）
• 📝 str: 文字列値（デフォルトの型）

📤 出力定義仕様

🤖 方法1: 出力ノードの自動検出

システムは次の一般的な出力ノードを自動的に検出します。

• 🖼️ SaveImage - 画像保存ノード
• 🎬 SaveVideo - ビデオ保存ノード
• 🔊 SaveAudio - 音声保存ノード
• 📹 VHS_SaveVideo - VHSビデオ保存ノード
• 🎵 VHS_SaveAudio - VHS音声保存ノード

🎯 方法2: 手動での出力マーキング

通常は複数の出力の場合に使用されます。 任意のノードのタイトルに$output.var_nameを使用して出力をマーキングします。

• ノードのタイトルを$output.resultに設定します。
• システムはこのノードの出力をツールの戻り値として使用します。

📄 ツール説明の設定（オプション）

ワークフローにMCPというタイトルのノードを追加して、ツールの説明を提供することができます。

1. String (Multiline)または同様のテキストノードを追加します（単一の文字列プロパティを持ち、ノードのフィールドはvalue、text、stringのいずれかである必要があります）。
2. ノードのタイトルをMCPに設定します。
3. 値フィールドに詳細なツール説明を入力します。

⚠️ 重要な注意事項

1. 🔒 パラメータ検証: オプションパラメータ（!がない）は、ノード内でデフォルト値が設定されている必要があります。
2. 🔗 ノードの接続: 他のノードに接続されているフィールドは、パラメータとして解析されません。
3. 🏷️ ツールの命名: エクスポートされたファイル名がツール名として使用されるため、意味のある英語名を使用してください。
4. 📋 詳細な説明: ユーザー体験を向上させるために、詳細なパラメータ説明を提供してください。
5. 🎯 エクスポート形式: API形式としてエクスポートする必要があり、UI形式としてエクスポートしないでください。

💬 コミュニティ

最新のアップデートと技術サポートのために、以下のQRコードをスキャンしてコミュニティに参加してください。

🤝 貢献の方法

すべての形式の貢献を歓迎します！開発者、デザイナー、ユーザーであれ、以下の方法でプロジェクトに参加できます。

🐛 問題の報告

• 📋 Issuesページでバグレポートを提出します。
• 🔍 提出する前に、類似の問題を検索してください。
• 📝 再現手順と環境を詳細に説明してください。

💡 機能提案

• 🚀 Issuesで機能要求を提出します。
• 💭 希望する機能とそのユースケースを説明してください。
• 🎯 ユーザー体験がどのように改善されるかを説明してください。

🔧 コードの貢献

📋 貢献のプロセス

1. 🍴 このリポジトリをあなたのGitHubアカウントにフォークします。
2. 🌿 機能ブランチを作成します: git checkout -b feature/your-feature-name
3. 💻 開発し、対応するテストを追加します。
4. 📝 変更をコミットします: git commit -m "feat: add your feature"
5. 📤 あなたのリポジトリにプッシュします: git push origin feature/your-feature-name
6. 🔄 メインリポジトリにプルリクエストを作成します。

🎨 コードスタイル

• 🐍 PythonコードはPEP 8スタイルガイドに従います。
• 📖 新しい機能に適切なドキュメントとコメントを追加してください。

🧩 ワークフローの貢献

• 📦 あなたのComfyUIワークフローをコミュニティと共有します。
• 🛠️ テスト済みのワークフローファイルを提出します。
• 📚 ワークフローの使用方法と例を追加してください。

🙏 謝辞

❤️ このプロジェクトの開発と実装をサポートしてくれた以下の組織、プロジェクト、チームに心から感謝します。

• 🧩 ComfyUI
• 💬 Chainlit
• 🔌 MCP
• 🎬 WanVideo
• ⚡ Flux

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています（LICENSE、SPDXライセンス識別子: MIT）。