{"id":31824555,"url":"https://github.com/skirja/vision-mcp","last_synced_at":"2026-04-13T01:33:11.349Z","repository":{"id":316636610,"uuid":"1063386038","full_name":"Skirja/vision-mcp","owner":"Skirja","description":"MCP server that adds visual understanding capabilities to text-only coding models. Supports OpenAI GPT-4o and compatible vision APIs.","archived":false,"fork":false,"pushed_at":"2026-01-16T03:40:35.000Z","size":63,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-16T18:26:37.474Z","etag":null,"topics":["image-analysis","mcp","openai","openai-compatible-api","ui-extraction","vision","visual-understanding"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Skirja.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-24T14:54:31.000Z","updated_at":"2026-01-16T03:39:58.000Z","dependencies_parsed_at":"2025-09-25T20:52:36.022Z","dependency_job_id":"41ca1e49-1d92-4fe0-9fa0-09331a0fbc7f","html_url":"https://github.com/Skirja/vision-mcp","commit_stats":null,"previous_names":["skirja/vision-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Skirja/vision-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skirja%2Fvision-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skirja%2Fvision-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skirja%2Fvision-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skirja%2Fvision-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Skirja","download_url":"https://codeload.github.com/Skirja/vision-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skirja%2Fvision-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31736723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-12T22:19:12.206Z","status":"ssl_error","status_checked_at":"2026-04-12T22:18:33.088Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-analysis","mcp","openai","openai-compatible-api","ui-extraction","vision","visual-understanding"],"created_at":"2025-10-11T15:45:07.235Z","updated_at":"2026-04-13T01:33:11.341Z","avatar_url":"https://github.com/Skirja.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vision MCP Server\n\nVision MCP Server adalah MCP (Model Context Protocol) server yang berfungsi sebagai \"mata\" untuk model AI yang tidak memiliki kemampuan bawaan untuk memproses gambar. Server ini memungkinkan model coding untuk menganalisis gambar melalui API yang kompatibel dengan OpenAI.\n\n## Cara Kerja\n\nVision MCP Server menjembatani komunikasi antara model coding (tanpa vision capabilities) dan vision model yang mendukung analisis gambar. Prosesnya sederhana:\n\n1. Model coding memberikan prompt dan path gambar ke MCP server\n2. Server mengkonversi gambar ke format base64\n3. Server mengirimkan prompt dan gambar ke vision model via API\n4. Server mengembalikan hasil analisis ke model coding\n\n## Fitur Utama\n\n- **Vision API Integration**: Menghubungkan model tanpa kemampuan vision dengan Vision Model\n- **Multi-Image Support**: Dapat menganalisis 1-10 gambar dalam satu permintaan\n- **Flexible Prompts**: Mendukung berbagai jenis permintaan (analisis UI, diagram, perbandingan dll)\n- **OpenAI Compatible**: Bekerja dengan berbagai provider yang kompatibel dengan OpenAI API\n- **Comprehensive Error Handling**: Penanganan error yang informatif dan user-friendly\n\n## Persyaratan\n\n- Node.js 18+ atau Bun 1.0+\n- API Key untuk vision model yang kompatibel dengan OpenAI\n\n## Instalasi\n\n```bash\n# Clone repository\ngit clone \u003crepository-url\u003e\ncd vision-mcp\n\n# Install dependencies\nbun install\n\n# Build project\nbun run build\n```\n\n## Konfigurasi\n\nServer memerlukan environment variables berikut:\n\n```bash\n# Required\nVISION_API_KEY=your_api_key_here\n\n# Optional\nVISION_API_BASE_URL=https://api.openai.com/v1  # Default: https://api.openai.com/v1\nVISION_MODEL_NAME=gpt-4o                      # Default: gpt-4o\nVISION_MAX_TOKENS=32000                       # Default: 32000\n```\n\n### Provider Vision Model yang Didukung\n\nVision MCP Server dapat bekerja dengan berbagai provider yang kompatibel dengan OpenAI API:\n\n1. **OpenAI**: Gunakan model seperti `gpt-4o` atau `gpt-4-vision-preview`\n2. **Custom Providers**: Atur `VISION_API_BASE_URL` ke endpoint provider Anda\n3. **Local Models**: Gunakan dengan server vLLM atau Ollama yang mendukung OpenAI-compatible API\n4. **Cloud Providers**: Banyak cloud provider menyediakan endpoint yang kompatibel\n\n## Penggunaan dengan MCP Client\n\n### Konfigurasi untuk Claude Desktop\n\nTambahkan konfigurasi berikut ke `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vision-mcp\": {\n      \"command\": \"bun\",\n      \"args\": [\"/path/to/vision-mcp/dist/index.js\"],\n      \"env\": {\n        \"VISION_API_BASE_URL\": \"https://llm.chutes.ai/v1\",\n        \"VISION_API_KEY\": \"your_api_key\",\n        \"VISION_MODEL_NAME\": \"Qwen/Qwen3-VL-235B-A22B-Instruct\",\n        \"VISION_MAX_TOKENS\": \"32000\"\n      }\n    }\n  }\n}\n```\n\n### Contoh Penggunaan\n\nSetelah dikonfigurasi, Anda dapat meminta model untuk menganalisis gambar seperti:\n\n```\n\"Analisis UI berikut dan berikan feedback tentang penggunaannya: /path/to/ui-screenshot.png\"\n```\n\n```\n\"Bandingkan kedua desain berikut dan sebutkan perbedaannya: /path/to/design1.png /path/to/design2.png\"\n```\n\n```\n\"Jelaskan alur yang ditunjukkan dalam diagram ini: /path/to/flow-diagram.png\"\n```\n\n#### Contoh dengan Claude Desktop\n\nDi chat Claude Desktop, Anda bisa menulis:\n\n```\nTolong analisis screenshot ini berikan masukan untuk UX improvement: /home/user/screenshots/app-login.png\n```\n\nClaude akan menggunakan Vision MCP Server untuk menganalisis gambar dan memberikan feedback.\n\n## Format Gambar yang Didukung\n\n- JPG/JPEG\n- PNG\n- GIF\n- WebP\n- BMP\n\n## Batasan\n\n- Maksimum 10 gambar per permintaan\n- Ukuran file maksimum 10MB per gambar\n- Path gambar harus absolute path atau valid relative path\n- Memerlukan koneksi internet untuk komunikasi dengan API\n\n## Struktur Proyek\n\n```\nvision-mcp/\n├── src/\n│   ├── index.ts           # Entry point utama\n│   ├── vision-tool.ts     # Implementasi vision tool\n│   ├── vision-client.ts   # Client untuk OpenAI API\n│   ├── file-handler.ts    # Utilitas pemrosesan file\n│   └── types.ts           # Tipe dan schema\n├── dist/                  # Output hasil build\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n## Pengembangan\n\n```bash\n# Development mode dengan auto-reload\nbun run dev\n\n# Type checking\nbun run typecheck\n\n# Build untuk produksi\nbun run build\n\n# Jalankan server\nbun start\n```\n\n## Testing\n\n### Testing dengan Client\n\nGunakan file test client yang disediakan:\n\n```bash\n# Set environment variables\nexport VISION_API_KEY=\"your_api_key\"\n\n# Run test client\nnode examples/test_client.js\n```\n\n### Langkah Testing\n\n1. **Pastikan environment variables terkonfigurasi**\n   ```bash\n   export VISION_API_BASE_URL=\"https://api.openai.com/v1\"\n   export VISION_API_KEY=\"your_api_key\"\n   export VISION_MODEL_NAME=\"gpt-4o\"\n   ```\n\n2. **Start MCP server**\n   ```bash\n   bun start\n   ```\n\n3. **Test dengan MCP client** (Claude Desktop, Cursor, dll)\n4. **Verifikasi vision tool tersedia** dan berfungsi dengan gambar uji\n\n## Troubleshooting\n\n### Error Common Issues\n\n1. **\"Image file not found\"**: Pastikan path file benar dan file dapat diakses\n2. **\"Authentication failed\"**: Periksa VISION_API_KEY Anda\n3. **\"Model not found\"**: Pastikan VISION_MODEL_NAME valid untuk API Anda\n4. **\"Rate limit exceeded\"**: Tunggu beberapa saat sebelum mencoba lagi\n\n### Tips Tambahan\n\n1. **Gunakan absolute paths** untuk menghindari masalah path resolution\n2. **Batas ukuran gambar**: Optimalkan gambar besar sebelum menganalisis\n3. **Cache respons**: Untuk gambar yang sama diulang, pertimbangkan cache\n4. **Monitoring**: Monitor penggunaan API untuk menghindari rate limits\n\n## Lisensi\n\nMIT License - lihat file [LICENSE](LICENSE) untuk detail.\n\n## Changelog\n\n### v2.0.0\n- Complete rewrite with improved architecture\n- Better error handling and validation\n- Enhanced type safety with Zod schemas\n- Improved file handling with support for multiple formats\n- Cleaner code structure and separation of concerns\n\n### v1.0.0\n- Initial release\n- Single vision tool implementation\n- Support for multiple image formats\n- OpenAI-compatible API integration\n- Comprehensive error handling\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskirja%2Fvision-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskirja%2Fvision-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskirja%2Fvision-mcp/lists"}