Vision MCP Server

비멀티모달 모델(DeepSeek, 구형 GPT-4, 로컬 소형 모델 등)에 연결된 에이전트에 시각 이해 기능을 제공하는 Model Context Protocol(MCP) 서버입니다. 에이전트가 이미지를 MCP 도구에 넘기면 서버가 비전 모델을 호출하고 텍스트를 반환합니다.

중국과 미국의 주요 제공업체와 모든 OpenAI 호환 엔드포인트를 지원합니다. 공식 SDK 우선, 구현 전 추상화, 침입 없는 제공업체 추가 방식입니다.

中文文档见 README.zh-CN.md

기능

• 4가지 도구: analyze_image / describe_image / ocr_image / list_providers, 모두 일반 Markdown 텍스트 반환

• 13개 내장 제공업체: OpenAI / Anthropic / Google Gemini / Qwen (DashScope) / Zhipu / Doubao (Volcengine) / ERNIE (Qianfan) / StepFun / Ollama / Alibaba Bailian / SiliconFlow / OpenRouter / 커스텀 OpenAI 호환 엔드포인트

• 세 가지 이미지 입력: 로컬 경로 / http(s) URL / base64 (data URI 또는 원시 base64), 자동 감지

• 3단계 폴백 체인: 공식 SDK → OpenAI 호환 엔드포인트 → 네이티브 fetch (SPEC §1 참조)

• 무상태(Stateless): 모든 호출은 독립적이며, 이미지와 결과는 절대 캐시되지 않고, 키는 환경 변수에서만 읽습니다.

Related MCP server: vision-mcp

빠른 시작

옵션 A: npx (npm에 배포됨, 저장소 불필요)

npx -y @inferai/vision-mcp

옵션 B: 로컬 빌드

git clone <repo> && cd vision-mcp
pnpm install
pnpm build
node dist/index.js

MCP 구성 예시 (stdio)

서버는 stdio 전송을 사용합니다. MCP 클라이언트가 프로세스를 생성하고 stdin/stdout을 통해 JSON-RPC 메시지를 교환합니다. 클라이언트가 MCP 서버를 정의하는 곳 어디에서나 구성하세요:

• Claude Code: 프로젝트 수준 .mcp.json 또는 사용자 수준 ~/.claude.json (mcpServers 키)

• Claude Desktop: claude_desktop_config.json

• 모든 MCP 클라이언트 (Cursor, 자체 제작 에이전트 등): 동일한 구조

npx 버전 (패키지 게시 후 사용 가능):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": ["-y", "@inferai/vision-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "DASHSCOPE_API_KEY": "sk-..."
      }
    }
  }
}

로컬 개발 (경로 조정, --env-file-if-exists=.env는 .env를 네이티브로 로드):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "node",
      "args": ["--env-file-if-exists=.env", "/absolute/path/to/vision-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

시작 인수 포함 (argv로 제공업체 기본값 재정의, 아래 참조):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@inferai/vision-mcp",
        "--default-provider=dashscope",
        "--siliconflow-api-key=sk-...",
        "--siliconflow-model=Qwen/Qwen2.5-VL-7B-Instruct"
      ],
      "env": {
        "DASHSCOPE_API_KEY": "sk-..."
      }
    }
  }
}

stdio 참고 사항:

• stdout은 MCP 프로토콜만 전달합니다. 서버는 절대 로그를 출력하지 않으며, 진단 정보는 stderr로 전송됩니다.

• 클라이언트가 프로세스 수명 주기를 관리합니다(시작 시 생성, 종료 시 종료). 데몬이 필요 없습니다.

• 첫 npx 실행 시 패키지를 다운로드하므로 몇 초가 걸릴 수 있습니다.

• 클라이언트가 셸 환경을 상속하는 경우 환경 변수는 셸 환경에서도 가져올 수 있습니다(env 블록 불필요).

MCP Inspector로 디버깅:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js --xxx-api-key=xxx --xxx2-api-key=xxx

변수 설정

1. MCP 구성 env 블록 (권장, 플랫폼 간 가장 안정적) — 위 env 객체에 변수 작성

2. .env 파일 (로컬 개발) — .env.example을 .env로 복사하고 작성한 후 node --env-file-if-exists=.env dist/index.js 실행 (Node 22 네이티브, dotenv 불필요)

3. 셸 export — export OPENAI_API_KEY=sk-xxx 후 실행

키가 없는 제공업체는 list_providers에서 사용 불가로 표시되며, 호출 시 누락된 변수를 보고합니다.

게시 (npx 작동 전)

pnpm publish          # or pnpm release (changeset flow)

환경 변수

모든 제공업체의 API_KEY, BASE_URL, MODEL은 환경 변수로 재정의할 수 있습니다(규칙: <PROVIDER_PREFIX>_API_KEY / <PROVIDER_PREFIX>_BASE_URL / <PROVIDER_PREFIX>_MODEL):

? = 선택 사항(내장 기본값 있음); * = 필수.

전역 구성:

폴백 체인

여러 제공업체를 사용할 수 있는 경우, 호출은 우선순위 체인을 따라 진행됩니다: 구성된 기본값 → VISION_MCP_PROVIDER_PRIORITY 목록 → 표 순서 (사용 불가 제공업체는 건너뜀).

• 각 제공업체는 제공업체 오류(업스트림 실패, 시간 초과) 시 VISION_MCP_MAX_RETRIES 횟수만큼 재시도됩니다.

• 제공업체가 재시도를 모두 소진하면 체인의 다음 사용 가능한 제공업체가 시도되며, 최대 VISION_MCP_MAX_FALLBACKS 폴백까지 허용됩니다.

• 제공업체 오류만 재시도/폴백을 트리거하며, 구성 또는 이미지 오류는 즉시 실패합니다.

• 명시적으로 요청된 provider 인수는 단독으로 시도됩니다(폴백 없음).

• 모든 것이 실패하면, 오류는 시도된 모든 제공업체와 각각의 마지막 오류를 나열합니다.

argv로도 사용 가능: --provider-priority=..., --max-retries=N, --max-fallbacks=N (환경 변수보다 우선).

MCP 시작 인수 (argv)

모든 제공업체의 apiKey / baseUrl / model은 시작 인수로 재정의할 수 있습니다(환경 변수보다 높은 우선순위), 형식 --<provider>-<field>:

node dist/index.js \
  --openai-api-key=sk-xxx \
  --openai-base-url=https://my-gateway.example.com/v1 \
  --openai-model=gpt-4o-mini \
  --dashscope-api-key=sk-xxx \
  --default-provider=dashscope

• 전역: --default-provider <name> / --default-model <name>

• 제공업체별: --<provider>-api-key, --<provider>-base-url, --<provider>-model (등호 또는 공백 형식 모두 작동)

• 모든 OpenAI 호환 타사 서비스: --openai-compat-base-url + --openai-compat-api-key + --openai-compat-model 한 줄로 연결; 또는 내장 제공업체의 base-url을 미러/프록시로 지정

우선순위: 도구 인수 provider/model > 시작 인수 (제공업체별 > 전역 기본값) > 환경 변수 > 제공업체 내장 기본값.

도구

image는 다음을 허용합니다: 로컬 경로 / http(s):// URL / data: URI / 원시 base64, 자동 감지.

보안 참고 사항: URL 다운로드는 SSRF로부터 보호됩니다. 모든 홉(리디렉션 포함)이 검증되며, 루프백, 사설 또는 링크-로컬 주소로 확인되는 URL은 차단됩니다(오류에 이유가 힌트로 표시됨).

제공업체 통합 (3단계 폴백 체인)

프로바이더 추가: OpenAI 호환 엔드포인트의 경우 src/core/config.ts의 RULES에 행 하나와 src/index.ts의 팩토리 테이블에 매핑 하나를 추가하면 됩니다 — 새 코드 없이 가능합니다. 공식 SDK 또는 네이티브 fetch 구현: SPEC §1 참조.

개발

pnpm check        # biome checks
pnpm test         # rstest unit tests (injected mocks, no network)
pnpm build        # rslib build

실제 호출 스모크 테스트(키가 구성된 프로바이더에 대해서만 실행, 그 외에는 건너뜀):

OPENAI_API_KEY=sk-... pnpm exec rstest tests/e2e

아키텍처

src/
├── index.ts            # Entry: composition root, stdio startup
├── core/               # Abstraction: interfaces / image loading / config / registry
├── providers/          # Adapters: official SDK or compatible endpoints, protocol conversion only
└── server/tools.ts     # MCP tool layer: zod validation + error mapping

전체 사양: SPEC.md.