MCP Vision Adapter

🎯 N8N 用 MCP Vision Adapter

🚀 N8N で YOLO による物体検出を実行 — ワンコマンドですぐに使えます！

MCP Vision Adapter は、N8N ユーザーが MCP Client Tool を使って Ultralytics YOLO モデルをすぐに実行できるように設計された、プロフェッショナルな Docker ソリューションです。

---

⚡ クイックスタート

1️⃣ リポジトリをダウンロードして起動

git clone https://github.com/MetehanYasar11/mcp-server-adapter.git
cd mcp-server-adapter
docker-compose up -d

2️⃣ N8N で MCP Client Tool を設定

N8N ワークフローに MCP Client Tool ノードを追加します。

• 接続タイプ：Server-Sent Events (SSE)
• SSE エンドポイント：http://mcp-vision-adapter:3000/sse
• 認証：None

Docker ネットワーク：N8N コンテナが mcp_network に接続されていることを確認してください。

3️⃣ テストしましょう！🎉

N8N で次の MCP ツールを使用できるようになります。

• detect_objects - 画像内の物体を検出します
• yolo_cli - 高度な YOLO コマンドを実行します

---

🏗️ システムアーキテクチャ

┌─────────────┐    SSE/HTTP    ┌─────────────────┐    REST API    ┌─────────────┐
│   N8N       │ ◄────────────► │ MCP Vision      │ ◄────────────► │ YOLO        │
│ Workflows   │                │ Adapter         │                │ Service     │
│             │                │ (Node.js)       │                │ (FastAPI)   │
└─────────────┘                └─────────────────┘                └─────────────┘
      │                               │                                    │
      │                               │                                    │
      ▼                               ▼                                    ▼
  Port 5678                      Port 3000                          Port 8080/8501
                                                                   (API + Streamlit)

---

🛠️ 機能

🔥 N8N 統合

• ✅ MCP Protocol 2024-03-26 標準
• ✅ Server-Sent Events (SSE) トランスポート層
• ✅ ゼロ設定で N8N に接続
• ✅ リアルタイム画像処理

🤖 Ultralytics YOLO

• ✅ YOLOv8n/s/m/l/x モデルに対応
• ✅ 物体検出とインスタンスセグメンテーション
• ✅ カスタムモデルをアップロード可能
• ✅ Streamlit Web UI による視覚的な管理

🐳 Docker の最適化

---

📋 MCP ツールと使い方

🎯 detect_objects

画像内の物体を検出します。

{
  "tool": "detect_objects",
  "input": {
    "image_path": "/path/to/image.jpg",
    "confidence": 0.5,
    "model": "yolov8n.pt"
  }
}

⚡ yolo_cli

高度な YOLO コマンドを実行します。

{
  "tool": "yolo_cli", 
  "input": {
    "command": "yolo predict model=yolov8s.pt source=image.jpg save=true"
  }
}

---

� インストールの詳細

Docker ネットワークへの接続

N8N を正しいネットワークに接続するには、次の手順を実行します。

# N8N container'ını MCP network'e bağla
docker network connect mcp_network <n8n_container_name>

# Veya N8N'i compose ile başlatırken:
# docker-compose.yml dosyanızda networks: [mcp_network] ekleyin

手動テスト

# MCP Adapter sağlık kontrolü
curl http://localhost:3000/health

# YOLO Service test
curl -F [email protected] http://localhost:8080/detect

# N8N'den MCP test (container içinden)
docker exec n8n curl http://mcp-vision-adapter:3000/health

---

🎨 Streamlit Web UI

YOLO モデルを視覚的に管理するには、次の機能を使用できます。

• URL：http://localhost:8501
• モデルのアップロード／切り替え
• ライブ画像分析
• バッチ処理

---

⚙️ 設定

環境変数

# MCP Adapter
PORT=3000
YOLO_SERVICE_URL=http://yolo:8080

# YOLO Service  
YOLO_MODEL_PATH=/weights/yolov8n.pt
UPLOAD_DIR=/tmp/uploads

カスタムモデル

# models/ klasörüne kendi modelinizi ekleyin
cp my_custom_yolo.pt models/

Docker Compose がモデルを自動的にコンテナにマウントします。

---

🧪 テストと開発

テストの実行

# Tüm testler
pytest tests/ -v

# Specific test
pytest tests/test_manual.py -v

# MCP protocol test
pytest tests/test_protocol.py -v

デバッグモード

# Adapter'ı debug mode'da çalıştır
DEBUG=1 docker-compose up

# Logları takip et
docker-compose logs -f mcp-vision-adapter

Ultralytics CLI の任意のコマンドを実行

Invoke-RestMethod -Uri "http://localhost:3000/execute" -Method Post -ContentType "application/json" -Body '{"tool":"yolo_cli","input":{"args":"train model=yolov8n.pt data=coco128.yaml epochs=1"}}'

---

STDIO モード（現在、VS Code Copilot ツールの実行には対応していません）

python -m mcp_vision_adapter.main

⚠️ **注意：**現在、STDIO 経由での VS Code Copilot ツールの実行には対応していません。完全に統合するには、HTTP API を使用してください。この問題は今後のアップデートで修正される予定です。

🤝 貢献

皆様からの貢献を歓迎します！ガイドラインについては CONTRIBUTING.md をご覧ください。このリポジトリは、従来型の自動化やツールを最新の LLM／エージェント環境につなぐためのハブを目指しています。ご質問や協業については、LinkedIn の Metehan Yaşar までご連絡ください。

---

---

🤝 貢献とサポート

💡 Issue の報告

• バグ報告：GitHub Issues で詳細な説明を添えて報告してください
• 機能リクエスト：新機能の提案を歓迎します
• N8N 統合：N8N に関する問題については、ログを添付してください

� 開発

# Fork repo
git clone https://github.com/YOUR_USERNAME/mcp-server-adapter.git
cd mcp-server-adapter

# Branch oluştur
git checkout -b feature/your-feature

# Test ve commit
pytest tests/ -v
git commit -m "feat: your awesome feature"
git push origin feature/your-feature

📞 お問い合わせ

• GitHub Issues：技術的な問題について
• Discussions：一般的な質問や提案について

---

📄 ライセンス

このプロジェクトは MIT ライセンス のもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。

🙏 謝辞

• Ultralytics - YOLOv8 モデルについて
• N8N - ワークフロー自動化プラットフォーム
• Microsoft - Model Context Protocol 標準について

---

⭐ 気に入ったら star を付けてください | 🍴 Fork してください | 🐛 Issue を作成してください

N8N コミュニティのために ❤️ を込めて作成

---

🧪 テスト

pip install fastapi uvicorn pytest
pytest -q

テスト：

• test_service_detect.py：YOLOv8 サービス（直接）
• test_adapter_proxy.py：アダプター → YOLOv8 サービス
• test_stdio_exec.py、test_exec_env.py：STDIO および環境変数のテスト
• すべてのテストは自動化されたエンドツーエンドテストです

---

📝 メモ

• 動画の場合は、start／end（例：?start=2s&end=5s）または frame パラメーターを使用してください。
• manual_result と MANUAL_RESULT のどちらも設定されておらず、アダプターが TTY で実行されていない場合は、プレースホルダーが返されます。

---

⚠️ ポートの競合

Uvicorn のポート 3000 が使用中の場合は、前のプロセスを停止する（CTRL-C）か、--port 3001 を指定して実行し、それに応じて mcp.json を更新してください。

---

🌍 オープンソースとライセンス

このプロジェクトは MIT ライセンスの下でオープンソースとして公開されています。コントリビューションを歓迎します！

---

セキュリティとプライバシー

• コードベースにシークレットキー、パスワード、アクセストークンは含まれていません。
• GITHUB_PERSONAL_ACCESS_TOKEN などのサンプル値は、ドキュメントおよびテスト目的でのみ使用されます。必ずご自身のキーを安全に使用してください。

---

🇹🇷 トルコ語ドキュメント

このプロジェクトにはトルコ語のドキュメントもあります。README.tr.md をご覧ください。