Vision MCP Server (TypeScript)

Локальный сервер Model Context Protocol, который оборачивает мультимодальную модель MiMo-V2.5 от Xiaomi как инструмент зрения для ИИ-агентов.

Text Agent (e.g. DeepSeek / Claude)
  → MCP Client → inspect_image tool
  → Local image sandbox + Sharp crop/scale
  → MiMo-V2.5 (vision model, Anthropic Messages API)
  → VisualObservation JSON
  → Agent continues reasoning

Предварительные требования

• Node.js >= 20

• Ключ API Xiaomi MiMo

Быстрый старт

git clone https://github.com/wenren93/mimo-vision-mcp.git
cd mimo-vision-mcp
npm install
cp .env.example .env
# Edit .env and set MIMO_API_KEY
npm run build
npm run demo -- /path/to/image.png "What is in this image?"

Запуск в качестве MCP-сервера

npm run start              # STDIO mode
npm run inspect            # MCP Inspector UI

Интеграция с Claude

claude mcp add vision \
  -e MIMO_API_KEY='your-key' \
  -e MIMO_BASE_URL='https://api.xiaomimimo.com/anthropic' \
  -e VISION_MODEL='mimo-v2.5' \
  -e VISION_ASSET_ROOT='/absolute/path/to/assets' \
  -- node /absolute/path/to/dist/server.js

📖 Полная документация на китайском ниже.

Документация на китайском — локальный MiMo Vision MCP (TypeScript)

Это полный конвейер без OpenRouter:

DeepSeek V4 Pro（纯文本主 Agent，Anthropic Messages 兼容 API）
  -> MCP Client
  -> 本地 inspect_image 工具
  -> 本地图片沙箱 + Sharp 裁剪/缩放
  -> MiMo-V2.5（Anthropic Messages 兼容 API）
  -> VisualObservation JSON
  -> DeepSeek 继续推理或操作浏览器

MiMo-V2.5 изначально поддерживает текст, изображения, видео и аудио, поэтому здесь он используется только как «визуальный датчик», обусловленный задачей. DeepSeek по-прежнему отвечает за планирование, вызов инструментов и итоговый ответ.

Проект включает:

• src/server.ts: STDIO Vision MCP Server.

• src/mimo-vision.ts: клиент понимания изображений MiMo-V2.5.

• src/demo-agent.ts: полная демонстрация цикла DeepSeek Official API + MCP-инструменты.

• src/add-asset.ts: безопасный импорт локальных изображений.

• src/asset-store.ts: границы файлов, перекодирование, обрезка и сопоставление координат.

• src/schemas.ts: Zod-схемы для вывода MiMo и вывода MCP.

Проект использует @modelcontextprotocol/server и @modelcontextprotocol/client из MCP TypeScript SDK v2; требуется Node.js 20 или выше. MCP TypeScript SDK

1. Рекомендуемый способ: локальный MCP + API Xiaomi MiMo

Установка:

cd mimo-vision-mcp
npm install
cp .env.example .env

Отредактируйте .env:

# MCP 视觉工具需要
MIMO_API_KEY=你的小米MiMo密钥
MIMO_BASE_URL=https://api.xiaomimimo.com/anthropic
VISION_MODEL=mimo-v2.5

# 仅端到端 Demo Agent 需要
DEEPSEEK_API_KEY=你的DeepSeek密钥
DEEPSEEK_BASE_URL=https://api.deepseek.com/anthropic
TEXT_MODEL=deepseek-v4-pro

VISION_ASSET_ROOT=./assets
VISION_MAX_FILE_MB=10
VISION_MAX_PIXELS=40000000
VISION_TIMEOUT_MS=45000

Адрес запроса MiMo — https://api.xiaomimimo.com/anthropic/v1/messages. Изображения передаются через Anthropic content block: type=image, source.type=base64, с отдельными полями media_type и чистыми данными Base64; публичный URL изображения не требуется. Понимание изображений MiMo; Anthropic Messages API MiMo

Related MCP server: VisionPower

2. Проверка полного конвейера одной командой

npm run demo -- /绝对路径/page.png "图中登录按钮在哪里？"

Процесс выполнения:

1. Изображение перекодируется в PNG, генерируется случайный assetId.

2. Демо запускает локальный MCP-сервер и читает список инструментов.

3. DeepSeek V4 Pro решает вызвать inspect_image.

4. MCP-сервер отправляет контролируемое изображение в mimo-v2.5.

5. MiMo возвращает OCR, визуальные доказательства и нормализованные координаты.

6. Zod проверяет выходные данные и сопоставляет координаты локальной обрезки с исходным изображением.

7. DeepSeek формирует ответ на основе визуальных наблюдений.

На стороне DeepSeek используется https://api.deepseek.com/anthropic/v1/messages, идентификатор модели — deepseek-v4-pro; маршрутизация через третьи стороны не используется. Anthropic API DeepSeek; Tool Calls DeepSeek

3. Отдельный запуск MCP-сервера

Самому MCP-серверу нужен только MIMO_API_KEY:

npm run build
npm run start

Использование MCP Inspector:

npm run inspect

Сначала импортируйте тестовое изображение:

npm run add-asset -- /绝对路径/page.png

MCP-сервер также предоставляет инструмент-мост import_image. Claude может сначала вызвать import_image({ sourcePath }), а затем передать возвращённый assetId в inspect_image:

claude mcp add vision \
  -e MIMO_API_KEY='你的 MiMo API Key' \
  -e MIMO_BASE_URL='https://api.xiaomimimo.com/anthropic' \
  -e VISION_MODEL='mimo-v2.5' \
  -e VISION_ASSET_ROOT='/绝对路径/mimo-vision-mcp/assets' \
  -- node /绝对路径/mimo-vision-mcp/dist/server.js

Порядок вызова:

import_image({ sourcePath: "/你的路径/page.png" })
→ { assetId: "img_....png" }
→ inspect_image({ assetId: "img_....png", goal: "找到登录按钮" })

При импорте изображение перекодируется в PNG и копируется в песочницу VISION_ASSET_ROOT.

Параметры вызова:

{
  "assetId": "img_生成的ID.png",
  "goal": "找到登录按钮并返回位置",
  "mode": "ui",
  "resolution": "auto"
}

4. Подключение собственного агента

Скопируйте mcp.config.example.json и замените пути и ключи на реальные значения:

{
  "mcpServers": {
    "vision": {
      "command": "node",
      "args": ["/绝对路径/mimo-vision-mcp/dist/server.js"],
      "env": {
        "MIMO_API_KEY": "你的密钥",
        "MIMO_BASE_URL": "https://api.xiaomimimo.com/anthropic",
        "VISION_MODEL": "mimo-v2.5",
        "VISION_ASSET_ROOT": "/绝对路径/mimo-vision-mcp/assets"
      }
    }
  }
}

Если обвязка агента использует Anthropic Messages, можно ориентироваться на src/demo-agent.ts:

1. client.listTools() читает инструменты MCP.

2. Сопоставьте MCP Schema с tools[].name/description/input_schema.

3. После получения content[].type=tool_use выполните client.callTool().

4. Поместите structuredContent в content block tool_result пользовательского сообщения и передайте его обратно в DeepSeek.

5. Развёртывание инференса MiMo-V2.5 локально

Приложение и MCP-часть по-прежнему используют TypeScript; для уровня инференса можно использовать vLLM с поддержкой Anthropic Messages API. После запуска совместимого сервиса нужно изменить только:

MIMO_BASE_URL=http://127.0.0.1:8000
MIMO_API_KEY=local
VISION_MODEL=mimo-v2.5

vLLM уже предоставляет конечную точку /v1/messages, совместимую с Anthropic. Основной способ запуска приведён ниже; реальные параметры параллелизма необходимо настраивать в зависимости от GPU-кластера:

vllm serve XiaomiMiMo/MiMo-V2.5 \
  --served-model-name mimo-v2.5 \
  --host 127.0.0.1 \
  --port 8000 \
  --trust-remote-code \
  --reasoning-parser qwen3

MiMo-V2.5 — это FP8 MoE с 310B общих параметров и 15B активных. 15B — это лишь объём активаций на каждый токен, а не вес, который нужно загрузить; обычный персональный компьютер не сможет практически разместить исходную модель. Официальное эталонное развёртывание использует параллельные вычисления на нескольких GPU. Карточка модели и развёртывание MiMo-V2.5; Anthropic Messages API vLLM

Таким образом, изображения не покидают локальную машину; но в примере главный агент DeepSeek по-прежнему вызывает официальный API DeepSeek. Если требуется полностью автономный конвейер, необходимо дополнительно развернуть основную текстовую модель.

6. Интеграция скриншотов браузера

Исполнитель браузера сохраняет скриншот текущего viewport в VISION_ASSET_ROOT:

const assetId = `shot_${crypto.randomUUID()}.png`;
await page.screenshot({
  path: path.join(process.env.VISION_ASSET_ROOT!, assetId),
  fullPage: false,
});

inspect_image возвращает координаты в диапазоне 0..1. Нажмите в центр:

const clickX = (box.x + box.width / 2) * viewport.width;
const clickY = (box.y + box.height / 2) * viewport.height;
await page.mouse.click(clickX, clickY);

По-прежнему рекомендуется отдавать приоритет DOM/Accessibility Tree, а визуальные данные использовать как запасной вариант. Перед кликом сделайте новый скриншот, чтобы прокрутка, анимация или всплывающие окна не сделали координаты недействительными.

7. JSON-вывод и границы безопасности

В документации MiMo, совместимой с Anthropic, в настоящее время не заявлены параметры response_format или строгой JSON Schema, поэтому этот проект не отправляет поля, специфичные для OpenAI, а делает следующее: системный промпт требует чистый JSON, в промпт встроена Schema, выполняется разбор JSON и строгая проверка Zod. Несоответствующие результаты завершаются ошибкой; полуструктурированный текст не передаётся главному агенту.

• Параметры MCP принимают только assetId, но не произвольные URL или абсолютные пути.

• Изображения можно читать только из VISION_ASSET_ROOT; при импорте они перекодируются и очищаются от метаданных.

• Ограничиваются размер файла и максимальное количество пикселей, чтобы снизить риск «картинной бомбы».

• Текст на изображениях считается ненадёжными данными и не может использоваться как инструкция для агента.

• В STDIO stdout — это канал MCP JSON-RPC; логи можно писать только в stderr.

8. Разработка

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 类型检查
npm run typecheck

# 代码检查
npm run lint
npm run lint:fix

# 代码格式化
npm run format
npm run format:check

# 运行测试
npm test

Тесты не вызывают внешние модели; они проверяют импорт изображений, сопоставление обрезки и реальное STDIO MCP-рукопожатие. Перед выпуском рекомендуется добавить регрессионные образцы для китайского OCR, веб-интерфейсов, размытых скриншотов, диаграмм и инъекций в промпты изображений.

9. Вклад

Приветствуется вклад! Подробнее см. в CONTRIBUTING.md.

10. Лицензия

Проект распространяется под лицензией MIT.