Vision MCP Server (TypeScript)

로컬 Model Context Protocol 서버로, Xiaomi의 MiMo-V2.5 멀티모달 모델을 AI 에이전트를 위한 비전 도구로 래핑합니다.

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

• Xiaomi MiMo API 키

빠른 시작

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 비전 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 서버.

• src/mimo-vision.ts: MiMo-V2.5 이미지 이해 클라이언트.

• src/demo-agent.ts: DeepSeek 공식 API + MCP 도구 루프의 전체 데모.

• src/add-asset.ts: 안전하게 로컬 이미지 가져오기.

• src/asset-store.ts: 파일 경계, 재인코딩, 크롭, 좌표 매핑.

• src/schemas.ts: MiMo 출력 및 MCP 출력의 Zod 스키마.

프로젝트는 MCP TypeScript SDK v2의 @modelcontextprotocol/server와 @modelcontextprotocol/client를 사용하며, Node.js 20 이상이 필요합니다. MCP TypeScript SDK

1. 권장 방식: 로컬 MCP + 小米 MiMo API

설치:

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 이미지 이해; MiMo Anthropic Messages API

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를 사용하며, 모델 ID는 deepseek-v4-pro입니다. 제3자 라우팅을 거치지 않습니다. DeepSeek Anthropic API; DeepSeek Tool Calls

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 스키마를 tools[].name/description/input_schema로 매핑합니다.

3. content[].type=tool_use를 받으면 client.callTool()을 실행합니다.

4. structuredContent를 사용자 메시지의 tool_result content block에 넣어 DeepSeek에 다시 제공합니다.

5. MiMo-V2.5 추론도 로컬에 배포

애플리케이션과 MCP 부분은 여전히 TypeScript를 사용합니다. 모델 추론 계층은 Anthropic Messages API를 지원하는 vLLM을 사용할 수 있습니다. 호환 서비스를 시작한 후 다음만 수정하면 됩니다:

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는 총 310B, 활성 15B 매개변수의 FP8 MoE 모델입니다. 15B는 단지 토큰당 활성화되는 양일 뿐이며, 15B 가중치만 로드하면 된다는 의미가 아닙니다. 일반 개인용 PC로는 원본 모델을 실용적으로 감당할 수 없습니다. 공식 참조 배포는 다중 GPU 병렬을 사용합니다. MiMo-V2.5 모델 카드 및 배포; vLLM Anthropic Messages API

이렇게 하면 이미지가 로컬을 벗어나지 않습니다. 그러나 예제의 DeepSeek 메인 에이전트는 여전히 DeepSeek 공식 API를 호출합니다. 전체 체인이 완전히 오프라인이어야 한다면 메인 텍스트 모델도 별도로 자체 호스팅해야 합니다.

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, 웹 UI, 흐린 스크린샷, 차트, 이미지 프롬프트 인젝션 회귀 샘플을 추가하는 것이 좋습니다.

9. 기여

기여를 환영합니다! 자세한 내용은 CONTRIBUTING.md를 읽어주세요.

10. 라이선스

이 프로젝트는 MIT 라이선스를 사용합니다.