텍스트 전용 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범용 이미지 이해 도구입니다. 경로와 선택적 사용자 지정 프롬프트를 지정하세요.
매개변수 | 필수 | 설명 |
| 예 | 로컬 이미지 경로 (절대 경로 또는 OpenCode의 cwd 기준 상대 경로) |
| 아니요 | 사용자 지정 지침. 기본값은 개발자 중심 설명입니다. |
ocr_image보이는 텍스트를 그대로 추출합니다. 오류 대화상자, 터미널 스크린샷, 촬영한 메모 등에 유용합니다.
매개변수 | 필수 | 설명 |
| 예 | 로컬 이미지 경로 (절대 경로 또는 OpenCode의 cwd 기준 상대 경로) |
두 도구 모두 PNG, JPEG, WEBP, GIF, HEIC/HEIF를 지원하며 기본 최대 20MB까지 허용합니다.
모든 설정은 환경 변수를 통해 이루어집니다(직접 설정하거나, 단독 실행 시 .env 파일에, 또는 opencode.json MCP 항목의 "environment" 블록에 설정):
변수 | 필수 | 기본값 | 설명 |
| 예 | — | Gemini API 키 |
| 아니요 |
| 비전을 지원하는 모든 Gemini 모델 |
| 아니요 |
| 이 크기보다 큰 이미지는 거부 |
서버는 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 참조.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | Optional custom instruction for what to look for or how to describe the image. If omitted, a general developer-focused description is returned. | |
| image_path | Yes | Path to a local image file (absolute, or relative to the directory OpenCode was started in). Supports PNG, JPEG, WEBP, GIF, HEIC/HEIF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | Path to a local image file to extract text from (absolute, or relative to the directory OpenCode was started in). Supports PNG, JPEG, WEBP, GIF, HEIC/HEIF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2analyze_imageocr_imageScored across 2 tools
The tool names suggest distinct purposes — one for general image analysis and one for OCR. However, the complete lack of descriptions introduces some ambiguity about their exact boundaries.
Both tools follow the same verb_noun pattern: analyze_image and ocr_image. The naming convention is clear, consistent, and predictable.
With only two tools, the server feels minimal and borderline thin for an image-related service. The count is not excessive, but it is at the low edge of what could be considered a functional toolset.
A vision-bridge server with only image analysis and OCR lacks obvious capabilities like object detection, image comparison, or metadata extraction. The surface appears significantly incomplete for a general vision service.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Generate images, GIFs, videos, and PDFs from HTML, URLs, or templates — from your AI agent.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
