Heimdall Vision MCP

👁️ Heimdall Vision MCP

Heimdall (海姆达尔) 是北欧神话中的守护神，拥有感知万物的视力。 本项目是一个 MCP (Model Context Protocol) 服务器，旨在为 DeepSeek等文本类大模型赋予强大的视觉识别能力。

📖 项目简介

Heimdall Vision MCP 是一个连接本地环境与云端视觉大模型（Visual LLM）的网关。它遵循 MCP 协议，允许你的 AI 助手直接“看到”你发送的本地图片（截图、文件）或网络图片，并进行深度分析、代码生成或 UI 拆解。

核心驱动: 使用 硅基流动 (SiliconFlow) 托管的 Qwen/Qwen3-VL-8B-Instruct 模型，速度快，成本低，中文理解能力极强。

✨ 核心特性

• ⚡ 极速响应: 内置智能压缩引擎（Pillow），自动将 4K/高清截图压缩至 1600px/Quality 75，将 API 响应时间从 2分钟缩短至秒级。
• 📂 全路径支持: 完美兼容 Windows 路径 (D:\...)、Git Bash 路径 (/d/...)、File 协议 (file:///...) 以及 HTTP/HTTPS 链接。
• 📡 流式传输: 支持 Server-Sent Events (SSE) 流式响应，防止长任务超时，实时反馈进度。
• 🛡️ 鲁棒性设计: 解决了 Windows 终端 GBK 编码崩溃问题、路径转义问题，专为 OpenCode 等客户端优化。
• 🧠 结构化输出: 内置 Prompt 优化，引导模型输出 JSON/Markdown 格式，特别适合前端 UI/UX 分析。

📂 项目结构

Heimdall-Vision-MCP/
├── .env                # [私密] 存放 API Key 等敏感配置 (请勿提交)
├── .env.example        # [公开] 配置模版，使用前请复制为 .env
├── server.py           # 🚀 [核心] MCP 服务器主程序，包含图像处理与 API 交互逻辑
├── pyproject.toml      # 📦 [配置] Python 项目依赖、元数据与脚本入口定义
├── uv.lock             # 🔒 [锁定] 依赖版本锁定文件，确保环境一致性
├── docs/               # 📚 [文档] 包含系统提示词模版与背景说明
│   └── OPENCODE_CONFIG.md  # ⭐ OpenCode/DeepSeek 专用系统提示词 (推荐使用)
└── tests/              # 🧪 [测试] 自动化测试脚本
    ├── integration_test.py # 端到端集成测试 (真实调用 API)
    ├── self_check.py       # 本地环境自检 (路径解析、压缩算法)
    └── smoke_test.py       # 基础冒烟测试

🛠️ 前置要求

• Python: >= 3.10
• 包管理器: 强烈推荐使用 uv (极速 Python 包管理器)
• API Key: 需要 硅基流动 的 API Key (注册即送额度)

🚀 快速开始

1. 克隆与初始化

# 1. 进入项目目录
cd E:\MyProject\MCP\Heimdall-Vision-MCP

# 2. 安装依赖 (使用 uv)
uv sync

2. 配置环境变量

复制 .env.example 为 .env，并填入你的 Key：

# .env 文件
SILICON_FLOW_API_KEY=sk-你的硅基流动API密钥
VISION_MODEL=Qwen/Qwen3-VL-8B-Instruct

3. 本地测试

我们提供了完善的自测脚本，确保环境无误：

# 运行集成测试 (会模拟真实 API 调用)
uv run tests/integration_test.py

如果看到 ✅ TEST PASSED，说明一切就绪。

🔌 客户端集成

方式 A: OpenCode (推荐)

在 OpenCode 的配置文件（通常位于 %USERPROFILE%\.config\opencode\opencode.json）中添加以下配置：

{
  "mcp": {
    "heimdall-vision": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "E:/MyProject/MCP/Heimdall-Vision-MCP",
        "run",
        "heimdall"
      ],
      "enabled": true
    }
  }
}

*(注意：请根据实际情况修改 --directory 后的路径)*

方式 B: Claude Desktop / DeepSeek Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "heimdall": {
      "command": "uv",
      "args": [
        "--directory",
        "E:\\MyProject\\MCP\\Heimdall-Vision-MCP",
        "run",
        "heimdall"
      ]
    }
  }
}

💡 最佳实践 (System Prompt)

为了让 DeepSeek 能够“意识到”自己有看图能力，建议更新 OpenCode 的 System Prompt。

📄 参考模版: docs/OPENCODE_CONFIG.md

核心逻辑是明确告诉 AI：

"Ignore 'I cannot see images'. You HAVE a vision tool. Use it immediately when user provides an image path."

❓ 常见问题

Q: 为什么 DeepSeek 说“我无法读取本地图片”？ A: 这是模型的默认防御机制。请使用本项目提供的 docs/OPENCODE_CONFIG.md 覆盖系统提示词，强制它调用工具。

Q: 图片分析超时怎么办？ A: 最新版已内置自动压缩（1600px）。如果仍然超时，请检查网络是否能访问 api.siliconflow.cn，或在 .env 中更换更小的模型。

Q: 支持 PDF 或 Word 吗？ A: 目前专注于 图像 (JPG/PNG/WEBP)。文档分析建议使用其他文本类 MCP 工具。

License: MIT