vision-bridge-mcp

텍스트 전용 OpenCode 에이전트에 눈을 달아 주세요.

OpenCode의 텍스트 전용 모델(예: DeepSeek V4)은 이미지를 읽을 수 없습니다. 따라서 오류 스크린샷, 화이트보드 스케치, UI 목업 사진을 첨부해도 에이전트는 그 내용을 전혀 알 수 없습니다. vision-bridge-mcp는 OpenCode에 바로 연결되는 작은 MCP 서버로, analyze_image(일반 설명/시각적 Q&A)와 ocr_image(정확한 텍스트 추출)라는 두 가지 도구를 추가합니다. 둘 다 Gemini API를 기반으로 합니다(기본값은 gemini-3.6-flash — 나중에 Google이 폐기하면 GEMINI_MODEL로 재정의하세요. 최신 모델 ID는 https://ai.google.dev/gemini-api/docs/models 참고).

설정이 끝나면 에이전트에게 파일을 보여 달라고 말하기만 하면 됩니다:

Look at ./screenshots/error.png and tell me what's failing.

그러면 에이전트가 스스로 analyze_image를 호출합니다. 채팅 창에 수동으로 복사/붙여넣기할 필요도, 별도의 CLI 단계도 없습니다.

요구 사항

• Node.js 18 이상

• 무료 Gemini API 키 — https://aistudio.google.com/apikey에서 발급 (무료 티어: 하루 1,500회 요청, 신용카드 불필요)

Related MCP server: Vision MCP Server

설치

클론할 필요가 없습니다. OpenCode 설정(opencode.json — 프로젝트 루트 또는 전역 설정용 ~/.config/opencode/opencode.json)에 다음을 추가하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vision-bridge": {
      "type": "local",
      "command": ["npx", "-y", "vision-bridge-mcp"],
      "environment": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

OpenCode를 다시 시작하면(또는 opencode mcp를 실행하여 다시 연결하면) analyze_image 및 ocr_image 도구가 자동으로 나타납니다. npx가 첫 실행 시 패키지를 다운로드하여 캐시하므로 직접 빌드하거나 설치할 필요가 없습니다.

설정 파일에 키를 하드코딩하는 대신 환경 변수를 선호하시나요? 셸 프로필에 GEMINI_API_KEY를 설정하고 "environment" 블록을 제거하세요. 어느 쪽이든 서버는 프로세스 환경에서 키를 읽습니다.

단독 실행(개발 또는 테스트용)

git clone https://github.com/YOUR_GITHUB_USERNAME/vision-bridge-mcp.git
cd vision-bridge-mcp
npm install
cp .env.example .env   # then fill in GEMINI_API_KEY
npm start

서버는 stdio를 통해 MCP를 사용하므로, 단독으로 실행하면 OpenCode 같은 클라이언트가 연결되기를 기다리며 대기만 합니다. 정상입니다.

도구

analyze_image

범용 이미지 이해 도구입니다. 경로와 선택적 사용자 지정 프롬프트를 지정하세요.

ocr_image

보이는 텍스트를 그대로 추출합니다. 오류 대화상자, 터미널 스크린샷, 촬영한 메모 등에 유용합니다.

두 도구 모두 PNG, JPEG, WEBP, GIF, HEIC/HEIF를 지원하며 기본 최대 20MB까지 허용합니다.

설정

모든 설정은 환경 변수를 통해 이루어집니다(직접 설정하거나, 단독 실행 시 .env 파일에, 또는 opencode.json MCP 항목의 "environment" 블록에 설정):

서버는 GEMINI_API_KEY가 설정되지 않아도 시작됩니다(opencode mcp가 여전히 도구를 나열할 수 있도록). 키 없이 도구가 실제로 호출되는 순간에만 명확한 메시지와 함께 오류를 반환합니다.

오류 처리

모든 도구 호출은 텍스트 결과로 성공하거나, isError: true와 함께 구체적이고 실행 가능한 메시지(파일 없음, 지원하지 않는 형식, 크기 제한 초과, API 키 누락/무효, 업스트림 Gemini 오류)와 함께 실패합니다. 서버 자체는 잘못된 호출로 인해 절대 중단되지 않습니다.

개발

npm install
npm test    # unit tests (node's built-in test runner, no network needed)
npm run lint

테스트 스위트는 경로 해석, MIME 유형 감지, 파일 검증(누락된 파일, 디렉터리, 빈 파일, 초과 크기 파일)을 다룹니다. 실제 사용에서 가장 문제가 될 수 있는 입력 처리 로직입니다. Gemini API 호출 자체는 라이브 키가 필요하므로 여기서 목킹/테스트하지 않습니다. 해당 경로를 확인하려면 GEMINI_API_KEY를 설정하고 npm start를 실행한 다음, 아무 MCP 클라이언트(또는 MCP Inspector)로 연결하세요.

게시 (관리자용)

npm login
npm publish --access public

먼저 package.json의 version을 올리세요. npx -y vision-bridge-mcp는 항상 최신 게시 버전을 해석합니다.

기여

CONTRIBUTING.md를 참조하세요.

라이선스

MIT — LICENSE 참조.