git clone <repo-url>
cd vision-mcp
npm install
npm run build

VLM_BASE_URL=https://api.openai.com/v1 \
VLM_API_KEY=sk-xxxx \
VLM_MODEL_ID=gpt-4o \
node dist/index.js

{
  "mcpServers": {
    "vision": {
      "command": "node",
      "args": ["/path/to/vision-mcp/dist/index.js"],
      "env": {
        "VLM_BASE_URL": "https://api.openai.com/v1",
        "VLM_API_KEY": "sk-xxxx",
        "VLM_MODEL_ID": "gpt-4o",
        "VISION_MCP_FONT_PATH": "/path/to/vision-mcp/fonts/SimHei.ttf"
      }
    }
  }
}

VLM_BASE_URL=... VLM_API_KEY=... VLM_MODEL_ID=... \
npm run inspector

{
  "detections": [
    {
      "label": "对象描述",
      "bbox": { "x_min": 0.1, "y_min": 0.2, "x_max": 0.3, "y_max": 0.4 },
      "confidence": 0.95
    }
  ]
}

{
  "text_blocks": [
    { "text": "文字内容", "bbox": { "x_min": 0.1, "y_min": 0.2, "x_max": 0.3, "y_max": 0.4 } }
  ],
  "full_text": "所有文字按阅读顺序拼接"
}

Agent: 我要找到这张图片中所有人的位置并标注出来

工具调用流程:
1. vision_detect(images=["photo.jpg"], target="人")
   → { detections: [{ label: "人", bbox: {x_min:0.1, y_min:0.2, x_max:0.3, y_max:0.5}, confidence: 0.9 }] }

2. image_draw_box(
     image="photo.jpg",
     boxes=[{ x:0.1, y:0.2, w:0.2, h:0.3, color:"#FF0000", label:"人" }],
     normalized=true,
     output_path="annotated.png"
   )
   → 返回标注后的图片

Agent: 提取这页 PPT 的所有文字内容

工具调用:
1. vision_ocr(images=["slide.png"])
   → { text_blocks: [...], full_text: "标题\n正文内容..." }

Agent: 检查这个页面截图的导航栏是否在顶部，按钮颜色是否为蓝色

工具调用:
1. vision_qa(images=["screenshot.png"], question="导航栏是否在页面顶部？按钮颜色是什么？")
   → "导航栏在页面顶部。按钮颜色为蓝色。"

Agent: 把这三张页面截图拼在一起，然后整体描述

工具调用:
1. image_concat(images=["p1.png","p2.png","p3.png"], layout="vertical")
   → 返回拼接后的图片

2. vision_describe(images=[拼接结果], detail_level="detailed")
   → 整体描述

vision-mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts                    # 入口：server 初始化 + stdio 传输
│   ├── constants.ts                # 环境变量、默认值、忠实性提示词
│   ├── types.ts                    # 共享类型定义
│   ├── schemas.ts                  # Zod 输入/输出 schema
│   ├── services/
│   │   ├── image-loader.ts         # 路径/URL → buffer + metadata
│   │   ├── vlm-client.ts           # OpenAI 兼容 VLM API 客户端
│   │   ├── image-processor.ts      # sharp: resize/crop/rotate/flip/concat
│   │   └── image-annotator.ts      # @napi-rs/canvas: draw_box/draw_text
│   └── tools/
│       ├── vlm.ts                  # 4 个 VLM 工具
│       └── image.ts                # 8 个图像处理工具
├── eval/
│   ├── setup.mjs                   # 测试图片生成
│   ├── evaluation.xml              # 评估问题
│   ├── test-all.mjs                # 完整测试脚本
│   └── images/                     # 测试图片
└── dist/                           # 编译输出

# 开发模式（热重载）
npm run dev

# 构建
npm run build

# 运行测试
node eval/test-all.mjs

# 生成测试图片
node eval/setup.mjs