MCP Vision Adapter

🎯 N8N 的 MCP Vision Adapter

🚀 使用 N8N 进行 YOLO 目标检测——一条命令即可就绪！

MCP Vision Adapter 是一款专业的 Docker 解决方案，旨在让 N8N 用户通过 MCP Client Tool 即刻运行 Ultralytics YOLO 模型。

---

⚡ 快速开始

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 了解相关指南。我们的目标是让此仓库成为连接传统自动化和工具与现代大模型/Agent 环境的枢纽。如有疑问或希望合作，请通过 LinkedIn 联系 Metehan Yaşar。

---

---

🤝 贡献与支持

💡 提交问题

• Bug 报告：在 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 标准

---

⭐ 喜欢的话请点星 | 🍴 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 文件。