Vision MCP Server (TypeScript)

Un servidor local de Model Context Protocol que envuelve el modelo multimodal MiMo-V2.5 de Xiaomi como herramienta de visión para agentes de IA.

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

Requisitos previos

• Node.js >= 20

• Una clave de API de Xiaomi MiMo

Inicio rápido

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

Ejecutar como servidor MCP

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

Integrar con 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

📖 Documentación completa en chino a continuación.

Documentación en chino — MCP de visión local de MiMo (TypeScript)

Este es un flujo completo que no pasa por 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 admite de forma nativa entradas de texto, imagen, video y audio, por lo que aquí solo se lo utiliza como un «sensor de visión» condicionado por la tarea. DeepSeek sigue siendo el responsable de la planificación, la llamada a herramientas y la respuesta final.

El proyecto incluye:

• src/server.ts: servidor de visión MCP por STDIO.

• src/mimo-vision.ts: cliente de comprensión de imágenes para MiMo-V2.5.

• src/demo-agent.ts: demostración completa del bucle de herramientas MCP + API oficial de DeepSeek.

• src/add-asset.ts: importación segura de imágenes locales.

• src/asset-store.ts: límites de archivo, recodificación, recorte y mapeo de coordenadas.

• src/schemas.ts: esquemas Zod para la salida de MiMo y la salida de MCP.

El proyecto utiliza @modelcontextprotocol/server y @modelcontextprotocol/client del MCP TypeScript SDK v2 y requiere Node.js 20 o superior. MCP TypeScript SDK

1. Método recomendado: MCP local + API de Xiaomi MiMo

Instalación:

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

Edita .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

La dirección de solicitud de MiMo es https://api.xiaomimimo.com/anthropic/v1/messages. Las imágenes usan el bloque de contenido de Anthropic: type=image, source.type=base64, y se pasan por separado media_type y los datos Base64 puros, sin necesidad de una URL pública de la imagen. Comprensión de imágenes de MiMo; API de mensajes de Anthropic de MiMo

Related MCP server: VisionPower

2. Verifica el flujo completo con un solo comando

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

Proceso de ejecución:

1. La imagen se recodifica como PNG y se genera un assetId aleatorio.

2. La demo inicia el servidor MCP local y lee la lista de herramientas.

3. DeepSeek V4 Pro decide llamar a inspect_image.

4. El servidor MCP envía la imagen controlada a mimo-v2.5.

5. MiMo devuelve OCR, evidencia visual y coordenadas normalizadas.

6. Zod valida la salida y mapea las coordenadas de recorte local de vuelta a la imagen original.

7. DeepSeek genera una respuesta basándose en las observaciones visuales.

DeepSeek utiliza https://api.deepseek.com/anthropic/v1/messages, con el ID de modelo deepseek-v4-pro, sin enrutamiento de terceros. API Anthropic de DeepSeek; Llamadas a herramientas de DeepSeek

3. Ejecutar el servidor MCP por separado

El servidor MCP solo necesita MIMO_API_KEY:

npm run build
npm run start

Usa MCP Inspector:

npm run inspect

Primero importa una imagen de prueba:

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

El servidor MCP también ofrece la herramienta puente import_image. Claude puede llamar primero a import_image({ sourcePath }) y luego pasar el assetId devuelto a 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

Orden de llamada:

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

Al importar, la imagen se recodifica como PNG y se copia en el sandbox VISION_ASSET_ROOT.

Parámetros de llamada:

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

4. Conectar con tu propio agente

Copia mcp.config.example.json y cambia las rutas y las claves por los valores reales:

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

Si el harness del agente usa Anthropic Messages, consulta src/demo-agent.ts:

1. client.listTools() lee las herramientas MCP.

2. Asigna el esquema MCP a tools[].name/description/input_schema.

3. Tras recibir content[].type=tool_use, ejecuta client.callTool().

4. Coloca structuredContent en el bloque de contenido tool_result del mensaje del usuario para retroalimentar a DeepSeek.

5. Desplegar también la inferencia de MiMo-V2.5 localmente

La aplicación y la parte MCP siguen usando TypeScript; la capa de inferencia del modelo puede usar vLLM, que admite la API de mensajes de Anthropic. Una vez iniciado el servicio compatible, solo hay que modificar:

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

vLLM ya ofrece el endpoint compatible con Anthropic /v1/messages. La forma principal de iniciarlo es la siguiente; los parámetros reales de paralelismo deben ajustarse según el clúster de 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 es un MoE FP8 con 310B de parámetros totales y 15B de parámetros activos. Los 15B son solo la cantidad activada por token, no significa que solo haya que cargar 15B de pesos; un PC personal normal no puede alojar de forma práctica el modelo original. El despliegue de referencia oficial usa paralelismo multi-GPU. Ficha del modelo y despliegue de MiMo-V2.5; API de mensajes de Anthropic de vLLM

De este modo las imágenes no salen de la máquina local; pero el agente principal DeepSeek del ejemplo sigue llamando a la API oficial de DeepSeek. Si se requiere que todo el flujo sea completamente offline, además hay que autohospedar el modelo de texto principal.

6. Integración de capturas de pantalla del navegador

El ejecutor del navegador escribe la captura del viewport actual en 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 devuelve coordenadas de 0..1. Haz clic en el punto central:

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

Se sigue recomendando priorizar el DOM/árbol de accesibilidad y usar la visión como respaldo. Vuelve a capturar la pantalla antes de hacer clic para evitar que el desplazamiento, las animaciones o las ventanas emergentes invaliden las coordenadas.

7. Salida JSON y límites de seguridad

La documentación compatible con Anthropic de MiMo actualmente no declara response_format ni parámetros estrictos de JSON Schema, por lo que este proyecto no envía campos exclusivos de OpenAI, sino que aplica: indicación del sistema que exige JSON puro, esquema incrustado en el prompt, análisis JSON y validación estricta con Zod. Los resultados no conformes fallan directamente y no se entrega texto semiestructurado al agente principal.

• Los parámetros MCP solo aceptan assetId, no URLs arbitrarias ni rutas absolutas.

• Las imágenes solo se pueden leer desde VISION_ASSET_ROOT; al importarlas se recodifican y se eliminan los metadatos.

• Se limita el tamaño del archivo y el número máximo de píxeles para reducir el riesgo de bombas de imagen.

• El texto dentro de las imágenes se considera datos no confiables y no puede usarse como instrucción para el agente.

• El stdout de STDIO es el canal JSON-RPC de MCP; los registros solo deben escribirse en stderr.

8. Desarrollo

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 类型检查
npm run typecheck

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

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

# 运行测试
npm test

Las pruebas no llaman a modelos externos; verifican la importación de imágenes, el mapeo de recortes y el handshake real de MCP por STDIO. Antes del lanzamiento, se recomienda añadir muestras de regresión para OCR en chino, UI web, capturas borrosas, gráficos e inyección de instrucciones en imágenes.

9. Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para más detalles.

10. Licencia

Este proyecto está bajo la Licencia MIT.