VisionAgent MCP Server

VisionAgent MCP 服务

Beta – v0.1
本项目处于早期访问阶段，在 v1.0 之前可能会有破坏性变更。

VisionAgent MCP 服务 v0.1 - 概述

现代大模型 “Agent” 通过 Model Context Protocol (MCP) 调用外部工具。VisionAgent MCP 是一个轻量级、旁挂式 MCP 服务，在本地通过 STDIN/STDOUT 运行，将来自 MCP 兼容客户端（Claude Desktop、Cursor、Cline 等）的每次工具调用转换为对 Landing AI 的 VisionAgent REST API 的经过身份验证的 HTTPS 请求。响应 JSON 以及任何图像或掩码都会流式传回模型，因此你可以直接在编辑器中发出自然语言的计算机视觉和文档分析命令，而无需编写自定义 REST 代码或加载额外的 SDK。

📸 演示

https://github.com/user-attachments/assets/2017fa01-0e7f-411c-a417-9f79562627b7

🧰 支持的用例 (v0.1)

每当 VisionAgent 发布新端点时，运行 npm run generate-tools。该脚本会获取最新的 OpenAPI 规范并自动重新生成本地工具映射。

🗺 目录

1. 快速开始
2. 配置
3. 示例提示词
4. 架构与流程
5. 开发者指南
6. 故障排除
7. 贡献
8. 安全与隐私

🚀 快速开始

获取你的 VisionAgent API 密钥

如果你还没有 VisionAgent API 密钥，请创建账户并获取你的 API 密钥。

# 1  Install
npm install -g vision-tools-mcp

# 2  Configure your MCP client with the following settings:
{
  "mcpServers": {
    "VisionAgent": {
      "command": "npx",
      "args": ["vision-tools-mcp"],
      "env": {
        "VISION_AGENT_API_KEY": "<YOUR_API_KEY>",
        "OUTPUT_DIRECTORY": "/path/to/output/directory",
        "IMAGE_DISPLAY_ENABLED": "true" # or false, see below
      }
    }
  }
}

3. 打开支持 MCP 的客户端。
4. 下载 street.png（从此目录中的 assets 文件夹获取，也可以选择任意测试图像）。
5. 粘贴以下提示词（或任意提示词）：

Detect all traffic lights in /path/to/mcp/vision-agent-mcp/assets/street.png

如果你的客户端支持内联资源，你将看到边界框叠加层；否则，PNG 会保存到你的输出目录，聊天中会显示其路径。

前提条件

⚙️ 配置

MCP 客户端配置示例（VS Code / Cursor 的 .mcp.json）

{
  "mcpServers": {
    "VisionAgent": {
      "command": "npx",
      "args": ["vision-tools-mcp"],
      "env": {
        "VISION_AGENT_API_KEY": "912jkefief09jfjkMfoklwOWdp9293jefklwfweLQWO9jfjkMfoklwDK",
        "OUTPUT_DIRECTORY": "/Users/me/documents/mcp/test",
        "IMAGE_DISPLAY_ENABLED": "false"
      }
    }
  }
}

对于不具备图像显示能力的 MCP 客户端（如 Cursor），请将 IMAGE_DISPLAY_ENABLED 设置为 False。对于具备图像显示能力的 MCP 客户端（如 Claude Desktop），请将 IMAGE_DISPLAY_ENABLED 设置为 true 以可视化工具输出。通常，支持资源的 MCP 客户端（参见此列表：https://modelcontextprotocol.io/clients）都支持图像显示。

💡 提示词示例

🏗 架构与流程

┌────────────────────┐ 1. human prompt            ┌───────────────────┐
│ MCP-capable client │───────────────────────────▶│  VisionAgent MCP │
│  (Cursor, Claude)  │                            │   (this repo)     │
└────────────────────┘                            └─────────▲─────────┘
            ▲  6. rendered PNG / JSON                     │ 2. JSON tool call
            │                                             │
            │ 5. preview path / data         3. HTTPS     │
            │                                             ▼
       local disk  ◀──────────┐                Landing AI VisionAgent
                               └──────────────  Cloud APIs
                                           4. JSON / media blob

1. 提示词 → 工具调用 客户端将你的自然语言提示词转换为结构化的 MCP 调用。
2. 验证 服务端使用从实时 OpenAPI 规范派生的 Zod schema 验证参数。
3. 转发 经过认证的 Axios 请求命中 VisionAgent 端点。
4. 响应 返回 JSON + 任何 base64 媒体。
5. 可视化 如果启用，则将掩码 / 边界框 / 深度图渲染到文件。
6. 返回聊天 MCP 客户端接收数据 + 文件路径（或内联预览）。

🧑‍💻 开发者指南

以下是如何深入了解代码、添加新端点或排查问题的方法。

安装与构建

1. 克隆仓库：

   git clone https://github.com/landing-ai/vision-agent-mcp.git
   

2. 进入项目目录：

   cd vision-agent-mcp
   

3. 安装依赖：

   npm install
   

4. 构建项目：

   npm run build
   

环境变量

• VISION_AGENT_API_KEY - 必填 用于 VisionAgent 认证的 API 密钥
• OUTPUT_DIRECTORY - 用于保存处理后输出的可选目录（支持相对路径和绝对路径）
• IMAGE_DISPLAY_ENABLED - 设置为 "true" 以启用图像可视化功能

客户端配置

构建完成后，使用以下设置配置你的 MCP 客户端：

{
  "mcpServers": {
    "VisionAgent": {
      "command": "node",
      "args": [
        "/path/to/build/index.js"
      ],
      "env": {
        "VISION_AGENT_API_KEY": "<YOUR_API_KEY>",
        "OUTPUT_DIRECTORY": "../../output",
        "IMAGE_DISPLAY_ENABLED": "true"
      }
    }
  }
}

注意： 将 /path/to/build/index.js 替换为构建后的 index.js 文件的实际路径，并根据需要设置环境变量。对于不具备图像显示能力的 MCP 客户端（如 Cursor），请将 IMAGE_DISPLAY_ENABLED 设置为 False。对于具备图像显示能力的 MCP 客户端（如 Claude Desktop），请将 IMAGE_DISPLAY_ENABLED 设置为 true 以可视化工具输出。通常，支持资源的 MCP 客户端（参见此列表：https://modelcontextprotocol.io/clients）都支持图像显示。

📑 脚本与命令

专业提示：如果你修改了 src/ 下的任何文件，或者想获取 VisionAgent 的新端点，请运行 npm run build:all 来重新编译 + 重新生成工具定义。

📂 项目结构

vision-agent-mcp/
├── .eslintrc.json              # ESLint config (optional)
├── .gitignore                  # Ignore node_modules, build/, .env, etc.
├── jest.config.js              # Placeholder for future unit tests
├── mcp-va.md                   # Draft docs (incomplete)
├── package.json                # npm metadata, scripts, dependencies
├── package-lock.json           # Lockfile
├── tsconfig.json               # TypeScript compiler config
├── .env                        # Your environment variables (not committed)
│
├── src/                        # TypeScript source code
│   ├── generateTools.ts        # Dev script: fetch OpenAPI → generate MCP tool definitions (Zod schemas)
│   ├── index.ts                # Entry point: load .env, start MCP server, handle signals
│   ├── toolDefinitionMap.ts    # Auto-generated MCP tool definitions (don’t edit by hand)
│   ├── toolUtils.ts            # Helpers to build MCP tool objects (metadata, descriptions)
│   ├── types.ts                # Core TS interfaces (MCP, environment config, etc.)
│   │
│   ├── server/                 # MCP server logic
│   │   ├── index.ts            # Create & start the MCP server (Server + Stdio transport)
│   │   ├── handlers.ts         # `handleListTools` & `handleCallTool` implementations
│   │   ├── visualization.ts    # Post-process & save image/video outputs (masks, boxes, depth maps)
│   │   └── config.ts           # Load & validate .env, export SERVER_CONFIG & EnvConfig
│   │
│   ├── utils/                  # Generic utilities
│   │   ├── file.ts             # File handling (base64 encode images/PDFs, read streams)
│   │   └── http.ts             # Axios wrappers & error formatting
│   │
│   └── validation/             # Zod schema generation & argument validation
│       └── schema.ts           # Convert JSON Schema → Zod, validate incoming tool args
│
├── build/                      # Compiled JavaScript (generated after `npm run build`)
│   ├── index.js
│   ├── generateTools.js
│   ├── toolDefinitionMap.js
│   └── …                       # Mirror of `src/` structure
│
├── output/                     # Runtime artifacts (bounding boxes, masks, depth maps, etc.)
│
└── assets/                     # Static assets (e.g., demo.gif)
    └── demo.gif

🔍 关键组件

1. src/generateTools.ts

   • 获取 https://api.va.landing.ai/openapi.json（VisionAgent 的公共 OpenAPI）。
   • 通过白名单过滤端点（你也可以禁用过滤以包含全部端点）。
   • 将 JSON Schema 转换为 Zod schema，写入 toolDefinitionMap.ts，其中包含一个 Map<string, McpToolDefinition>。
   • 运行：npm run generate-tools。

2. src/toolDefinitionMap.ts

   • 包含工具名称 → MCP 定义的映射（名称、描述、inputSchema、端点、HTTP 方法）。
   • 自动生成——请勿手动编辑。

3. src/server/handlers.ts

   • 实现 handleListTools：返回 [ { name, description, inputSchema } ]。

   • 实现 handleCallTool：

     • 使用 Zod 验证传入的 arguments。
     • 如果参数基于文件（例如 imagePath、pdfPath），则通过 src/utils/file.ts 读取并进行 base64 编码。
     • 为 Axios 构建 multipart/form-data 或 JSON 载荷。
     • 调用 VisionAgent 端点，捕获错误，返回符合 MCP 规范的 JSON 响应。
     • 如果 IMAGE_DISPLAY_ENABLED=true，则调用 src/server/visualization.ts 保存 PNG/JSON。

4. src/server/visualization.ts

   • 对掩码进行后处理（base64 → PNG）。
   • 可选地在原始图像上叠加边界框或分割掩码，并保存到 OUTPUT_DIRECTORY。
   • 在 MCP 结果中返回文件路径，以便你的客户端可以渲染它们。

5. src/utils/file.ts

   • readFileAsBase64(path: string): Promise<string>：读取任意二进制文件（图像、PDF、视频）并返回 base64。
   • loadFileStream(path: string)：返回用于大文件上传的 Node.js 流。

6. src/utils/http.ts

   • 配置 Axios，基础 URL 为 https://api.va.landing.ai。
   • 添加 Authorization: Bearer ${VISION_AGENT_API_KEY} 请求头。
   • 封装对 VisionAgent 端点的调用，处理 4xx/5xx，将错误格式化为 MCP 错误对象。

7. src/validation/schema.ts

   • 包含将 JSON Schema（来自 OpenAPI）转换为 Zod 的辅助函数。
   • 暴露一个函数 buildZodSchema(jsonSchema: any): ZodObject，供 generateTools.ts 使用。

8. src/index.ts

   • 加载 dotenv（读取 .env）。

   • 验证必需的环境变量（VISION_AGENT_API_KEY）。

   • 导入生成的 toolDefinitionMap。

   • 创建一个 MCP Server（来自 @modelcontextprotocol/sdk/server），使用 StdioServerTransport。

   • 将 ListTools → handleListTools、CallTool → handleCallTool 连接起来。

   • 记录启动信息：

     vision-tools-api MCP Server (v0.1.0) running on stdio, proxying to https://api.va.landing.ai
     

   • 监听 SIGINT/SIGTERM 以优雅关闭。

🚧 错误处理与日志

• 验证错误 如果你发送无效或缺失的参数，服务器会返回：

  {
    "id": 3,
    "error": {
      "code": -32602,
      "message": "Validation error: missing required parameter ‘imagePath’"
    }
  }
  

• 网络错误 Axios 错误（超时、5xx）会被捕获并返回为：

  {
    "id": 4,
    "error": {
      "code": -32000,
      "message": "VisionAgent API error: 502 Bad Gateway"
    }
  }
  

• 内部异常 处理器中未捕获的异常会产生：

  {
    "id": 5,
    "error": {
      "code": -32603,
      "message": "Internal error: Unexpected token in JSON at position 345"
    }
  }
  

🛟 故障排查

npm run generate-tools
npm start

其他问题请参阅 MCP 文档：https://modelcontextprotocol.io/quickstart/user

另请注意，特定客户端会提供各自的实用文档。例如，如果你使用的是 OpenAI Agents SDK，请参阅其文档：https://openai.github.io/openai-agents-python/mcp/

🤝 贡献

我们欢迎 PR！

1. Fork → git checkout -b feature/my-feature。
2. npm run typecheck（无错误）
3. 提交 PR，说明做了什么以及为什么。

🔒 安全与隐私

• MCP 服务在本地运行，因此除了你显式调用的 Landing AI API 端点外，文件不会被转发到任何地方。
• 输出图像/掩码仅写入你机器上的 OUTPUT_DIRECTORY。
• 本项目不收集任何遥测数据。

由 LandingAI 团队用 ❤️ 打造。