vision-bridge-mcp

Vision 사이드카 MCP 서버 — 텍스트 전용 LLM이 이미지를 볼 수 있게 해줍니다. OpenAI 및 Anthropic API 형식을 기본 지원합니다. 모델 기능 기반 라우팅 스킬을 포함합니다.

왜?

대부분의 LLM은 텍스트 전용입니다 — 이미지를 볼 수 없습니다. 이 MCP 서버는 이미지를 비전 가능 모델로 전달하고 텍스트 결과를 반환하여 그 격차를 해소합니다. OpenAI 호환 또는 Anthropic 호환 API 엔드포인트와 함께 작동합니다.

vision-sidecar 스킬과 함께 사용하면 호스트 모델의 기능에 따라 자동으로 라우팅됩니다:

예외: 시스템 클립보드에 이미지가 있고 대화에 경로/URL/첨부 파일이 없는 경우, 멀티모달 호스트 모델도 image="clipboard"를 전달할 수 있습니다.

Related MCP server: Vision MCP Server

특징

• ✅ 세 가지 도구: analyze_image, ocr_image, compare_images

• ✅ 이중 프로토콜: OpenAI chat/completions 및 Anthropic messages 형식

• ✅ 클립보드 지원: Windows (PowerShell) + macOS (Swift)

• ✅ SHA256 파일 캐시 (설정 가능한 TTL)

• ✅ URL 다운로드 재시도: 통과 실패 시 원격 URL을 자동으로 base64로 다운로드

• ✅ 추론 모델 폴백: content가 null일 때 reasoning_content 추출

• ✅ 전체 체인 타임아웃: 연결 + 헤더 + 본문 읽기

• ✅ 안전 제한: 16MB 응답 / 20MB 이미지 / 1MB 오류 세부 정보

• ✅ 타입화된 오류: VisionInputError / VisionApiError / VisionTimeoutError

• ✅ 포괄적인 테스트: 30개 이상의 단위 테스트 + 종단 간 스모크 테스트

• ✅ 새로운 npm 종속성 없음 (워크스페이스 node_modules 사용)

빠른 시작

1. node ≥ 18이 PATH에 있는지 확인하세요.

2. 환경 변수를 설정하세요:

export VISION_API_BASE_URL=https://api.example.com/v1   # OpenAI: ends with /v1; Anthropic: base without /v1
export VISION_API_KEY=sk-...                             # API key
export VISION_MODEL=gpt-4o                               # Vision model name
# Optional: export VISION_API_FORMAT=anthropic            # openai (default) or anthropic

3. MCP 클라이언트 설정에 등록하세요:

{
  "id": "vision-bridge-mcp",
  "transport": "stdio",
  "command": "node",
  "args": ["server.js"],
  "cwd": "/path/to/vision-bridge-mcp",
  "env": {
    "VISION_API_BASE_URL": "https://api.example.com/v1",
    "VISION_API_KEY": "your-key",
    "VISION_MODEL": "gpt-4o"
  },
  "enabled": true
}

설정

시작 시 처음 세 변수를 검증합니다. 누락된 경우 읽기 쉬운 오류를 표시하고 종료합니다(코드 1).

도구

analyze_image

전제 조건: 호스트 모델에 멀티모달 비전이 없는 경우에만 호출하세요. 호스트 모델이 멀티모달인 경우 네이티브 이미지 이해를 사용하세요.

• image (필수, 문자열): 로컬 파일 경로 / http(s) URL / base64 dataURL / clipboard.

  • 로컬 경로: 확장자에서 MIME 유형 추론(png/jpg/jpeg/gif/webp/bmp), base64 dataURL로 변환.

  • http(s) URL: image_url로 직접 전달.

  • dataURL: image/* base64 인코딩만 허용.

  • clipboard / clip / pasteboard: 현재 시스템 클립보드 이미지 읽기(Windows: scripts/clipboard.ps1, macOS: scripts/clipboard.swift), 임시 PNG로 저장 후 정규화. Linux는 지원되지 않음.

• prompt (선택 사항, 문자열): 사용자 정의 인식 지침. 기본값: "이 이미지를 자세히 설명해 주세요."

• 반환: 성공 시 { content: [{ type: "text", text }] }; 실패 시 { content: [{ type: "text", text: "[vision_error] ..." }], isError: true }.

내부 요청 (VISION_API_FORMAT에 따라 분기):

• OpenAI: POST {base}/chat/completions, 이미지를 image_url 부분으로, 인증 Authorization: Bearer.

• Anthropic: POST {base}/v1/messages, 이미지를 image 블록으로 (source: {type: base64, media_type, data} 또는 {type: url, url}), 인증 x-api-key + anthropic-version: 2023-06-01 (호환성을 위해 Authorization: Bearer도 전송).

기본 타임아웃: 60초 (연결 + 본문 읽기 포함).

안전 제한: API 응답 16MB, 이미지 다운로드 20MB (content-length 사전 확인 + 실제 크기 재확인).

동작 참고 사항 (실제 모델 테스트 기반):

• 추론 모델은 content: null을 반환하고 답변이 reasoning_content에 있을 수 있음 — 자동으로 폴백.

• http(s) URL 통과 실패 시 미디어/다운로드 오류 → 자동으로 base64로 다운로드하고 한 번 재시도.

ocr_image

• image (필수, 문자열): analyze_image와 동일한 정규화.

• languages (선택 사항, 문자열): 언어 힌트 (예: zh,en).

• format (선택 사항, 열거형): plain (기본값, 레이아웃을 유지한 일반 텍스트) / markdown (제목/목록/표 유지) / json (text + type이 있는 blocks 배열 반환).

• 내부적으로 image_url.detail = "high" 사용; 형식별로 프롬프트 주입.

compare_images

• images (필수, 배열, 2–4개): 각각 로컬 경로 / http(s) URL / dataURL / 클립보드 지원.

• prompt (선택 사항, 문자열): 사용자 정의 비교 지침. 기본값: "이 이미지들을 비교하고 차이점과 유사점을 설명해 주세요."

• 텍스트 + 여러 image_url 부분 (detail = "auto")이 포함된 단일 사용자 메시지.

• URL이 미디어/다운로드 오류로 실패하면 모든 URL을 base64로 다운로드하고 한 번 재시도.

Vision Sidecar 스킬

vision-sidecar 스킬은 모델 기능 기반 라우팅을 제공합니다. MCP 클라이언트에서 활성화하면:

• 호스트 모델이 멀티모달 → 네이티브 이미지 이해 사용 (MCP 호출 없음)

• 호스트 모델이 텍스트 전용 → 이 MCP의 analyze_image 호출

• 예외: 멀티모달 호스트 모델에서 클립보드 읽기 가능

스킬이 없으면 호스트 모델의 동작은 완전히 변경되지 않습니다 — 침입 제로.

스킬 파일은 skill/vision-sidecar.md를 참조하세요.

캐싱

기본적으로 활성화됩니다. 동일한 "이미지 + 프롬프트" 조합에 대한 비전 API 결과를 캐시합니다.

• 키: SHA256(이미지 식별자 + "::" + 프롬프트). 로컬 파일/dataURL은 base64 콘텐츠로 해시; http(s) URL은 URL 문자열로 해시.

• 저장: 키당 하나의 JSON 파일 ({ result, cachedAt }), 캐시 디렉터리에 저장.

• TTL: 기본 1시간. 만료된 항목은 다음 접근 시 자동 삭제.

• 비활성화: VISION_CACHE_TTL=0 (또는 음수).

• 참고: 키에 모델 이름이 포함되지 않습니다. VISION_MODEL을 변경한 후 TTL 기간 동안 이전 모델의 캐시 결과가 반환될 수 있습니다 — 모델 변경 시 캐시 디렉터리를 비우세요.

테스트

cd vision-bridge-mcp
node --test

• test/vision.test.js: 핵심 라이브러리 단위 테스트 (입력 정규화 / 메시지 본문 / API 호출 / 오류 매핑 / 타임아웃 / 캐시 / URL 재시도 / OCR / 클립보드).

• test/cache.test.js: 캐시 모듈 테스트 (키 안정성 / 적중 / 만료 / 손상된 JSON / 하위 호환성).

• test/smoke.test.mjs: 종단 간 스모크 테스트 — stdio를 통해 실제 server.js를 실행하고, 로컬 HTTP 스텁을 사용하여 비전 모델을 시뮬레이션하며, tools/list 및 도구 호출을 검증합니다.

다른 Vision MCP와의 비교

다른 비전 MCP 프로젝트와의 자세한 비교는 docs/COMPARISON.md를 참조하세요.

라이선스

MIT