Vision MCP Server (TypeScript)

Ein lokaler Model Context Protocol-Server, der das multimodale Modell MiMo-V2.5 von Xiaomi als Vision-Tool für KI-Agenten kapselt.

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

Voraussetzungen

• Node.js >= 20

• Ein Xiaomi MiMo API-Schlüssel

Schnellstart

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?"

Als MCP-Server ausführen

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

In Claude integrieren

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

📖 Vollständige Dokumentation auf Chinesisch unten.

Chinesische Dokumentation — Lokaler MiMo-Vision-MCP (TypeScript)

Dies ist eine vollständige Pipeline, die nicht über OpenRouter läuft:

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

MiMo-V2.5 unterstützt nativ Text-, Bild-, Video- und Audioeingaben. Daher wird es hier nur als aufgabenkonditionierter „visueller Sensor“ verwendet. DeepSeek ist weiterhin für Planung, Tool-Aufrufe und die endgültige Antwort verantwortlich.

Das Projekt enthält:

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

• src/mimo-vision.ts: MiMo-V2.5-Bildverständnis-Client.

• src/demo-agent.ts: Vollständige Demo mit offizieller DeepSeek-API und MCP-Tool-Schleife.

• src/add-asset.ts: Sicherer Import lokaler Bilder.

• src/asset-store.ts: Dateigrenzen, Neucodierung, Zuschneiden und Koordinatenabbildung.

• src/schemas.ts: Zod-Schemas für MiMo-Ausgabe und MCP-Ausgabe.

Das Projekt verwendet @modelcontextprotocol/server und @modelcontextprotocol/client aus dem MCP TypeScript SDK v2 und benötigt Node.js 20 oder höher. MCP TypeScript SDK

1. Empfohlener Ansatz: Lokaler MCP + 小米 MiMo API

Installation:

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

.env bearbeiten:

# 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

Die MiMo-Anfrageadresse lautet https://api.xiaomimimo.com/anthropic/v1/messages. Bilder werden mit einem Anthropic-Content-Block übergeben: type=image, source.type=base64, wobei media_type und die reinen Base64-Daten getrennt übergeben werden; eine öffentliche Bild-URL ist nicht erforderlich. MiMo Bildverständnis; MiMo Anthropic Messages API

Related MCP server: VisionPower

2. Die gesamte Pipeline mit einem einzigen Befehl verifizieren

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

Ablauf:

1. Das Bild wird als PNG neu codiert und eine zufällige assetId generiert.

2. Die Demo startet den lokalen MCP-Server und liest die Werkzeugliste.

3. DeepSeek V4 Pro entscheidet, inspect_image aufzurufen.

4. Der MCP-Server sendet das kontrollierte Bild an mimo-v2.5.

5. MiMo liefert OCR, visuelle Belege und normalisierte Koordinaten.

6. Zod validiert die Ausgabe und bildet die lokalen Zuschneidekoordinaten auf das Originalbild ab.

7. DeepSeek erzeugt die Antwort auf Basis der visuellen Beobachtung.

Auf der DeepSeek-Seite wird https://api.deepseek.com/anthropic/v1/messages verwendet; die Modell-ID ist deepseek-v4-pro. Es wird nicht über Dritte geroutet. DeepSeek Anthropic API; DeepSeek Tool Calls

3. MCP-Server eigenständig ausführen

Der MCP-Server selbst benötigt nur MIMO_API_KEY:

npm run build
npm run start

MCP Inspector verwenden:

npm run inspect

Zuerst ein Testbild importieren:

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

Der MCP-Server bietet auch das Brückenwerkzeug import_image. Claude kann zuerst import_image({ sourcePath }) aufrufen und dann die zurückgegebene assetId an inspect_image übergeben:

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

Aufrufreihenfolge:

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

Beim Import wird das Bild als PNG neu codiert und in die Sandbox VISION_ASSET_ROOT kopiert.

Aufrufparameter:

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

4. Einbindung in einen eigenen Agenten

Kopieren Sie mcp.config.example.json und ändern Sie Pfad und Schlüssel auf die tatsächlichen Werte:

{
  "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"
      }
    }
  }
}

Wenn der Agent-Harness Anthropic Messages verwendet, finden Sie ein Beispiel in src/demo-agent.ts:

1. client.listTools() liest die MCP-Tools.

2. Das MCP-Schema wird auf tools[].name/description/input_schema abgebildet.

3. Nach dem Empfang von content[].type=tool_use wird client.callTool() ausgeführt.

4. structuredContent wird in den tool_result-Content-Block der Benutzernachricht eingefügt und an DeepSeek zurückgegeben.

5. MiMo-V2.5-Inferenz ebenfalls lokal bereitstellen

Anwendung und MCP-Teil verwenden weiterhin TypeScript; für die Modellinferenzschicht kann vLLM verwendet werden, das die Anthropic Messages API unterstützt. Nach dem Start des kompatiblen Dienstes muss nur Folgendes geändert werden:

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

vLLM bietet bereits einen Anthropic-kompatiblen Endpunkt unter /v1/messages. Die zentrale Startmethode lautet wie folgt; die tatsächlichen Parallelitätsparameter müssen an den GPU-Cluster angepasst werden:

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 ist ein FP8-MoE mit 310B Gesamtparametern und 15B aktivierten Parametern. 15B ist nur die Aktivierungsmenge pro Token, was nicht bedeutet, dass nur 15B Gewichte geladen werden müssen; ein normaler PC kann das Originalmodell nicht praktikabel ausführen. Die offizielle Referenzbereitstellung erfolgt mit mehreren GPUs parallel. MiMo-V2.5 Modellkarte und Bereitstellung; vLLM Anthropic Messages API

Auf diese Weise verlassen Bilder den Computer nicht; der DeepSeek-Hauptagent im Beispiel ruft jedoch weiterhin die offizielle DeepSeek-API auf. Wenn die gesamte Pipeline vollständig offline sein soll, muss zusätzlich das Haupttextmodell selbst gehostet werden.

6. Browser-Screenshot-Anbindung

Der Browser-Executor schreibt den aktuellen Viewport-Screenshot in 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 gibt Koordinaten von 0 bis 1 zurück. Klicken Sie auf den Mittelpunkt:

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

Es wird weiterhin empfohlen, zuerst den DOM-/Accessibility-Tree zu verwenden und die visuelle Methode als Fallback einzusetzen. Erstellen Sie vor dem Klicken einen neuen Screenshot, damit Scrollen, Animationen oder Pop-ups die Koordinaten nicht ungültig machen.

7. JSON-Ausgabe und Sicherheitsgrenzen

Die Anthropic-kompatible Dokumentation von MiMo deklariert derzeit weder response_format noch strenge JSON-Schema-Parameter. Daher sendet dieses Projekt keine OpenAI-spezifischen Felder, sondern führt Folgendes aus: Der Systemprompt verlangt reines JSON, das Schema wird in den Prompt eingebettet, JSON wird geparst und mit Zod strikt validiert. Nicht konforme Ergebnisse schlagen direkt fehl; halbstrukturierter Text wird nicht an den Hauptagenten übergeben.

• MCP-Parameter akzeptieren nur assetId, keine beliebige URL und keine absoluten Pfade.

• Bilder können nur aus VISION_ASSET_ROOT gelesen werden; beim Import werden sie neu codiert und Metadaten entfernt.

• Dateigröße und maximale Pixelanzahl werden begrenzt, um das Risiko von Bildbomben zu verringern.

• Text in Bildern wird als nicht vertrauenswürdige Daten behandelt und kann nicht als Anweisung für den Agenten verwendet werden.

• Der stdout von STDIO ist der MCP-JSON-RPC-Kanal; Logs dürfen nur auf stderr geschrieben werden.

8. Entwicklung

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 类型检查
npm run typecheck

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

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

# 运行测试
npm test

Die Tests rufen keine externen Modelle auf; sie validieren den Bildimport, die Zuschneidezuordnung und den echten STDIO-MCP-Handshake. Vor der Veröffentlichung wird empfohlen, Regressionstestbeispiele für chinesische OCR, Web-Oberflächen, unscharfe Screenshots, Diagramme und Bild-Prompt-Injection hinzuzufügen.

9. Beiträge

Beiträge sind willkommen! Weitere Informationen finden Sie in CONTRIBUTING.md.

10. Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.