使用说明

Vision MCP Server

Vision 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.

Cara Kerja

Vision MCP Server menjembatani komunikasi antara model coding (tanpa vision capabilities) dan vision model yang mendukung analisis gambar. Prosesnya sederhana:

Model coding memberikan prompt dan path gambar ke MCP server
Server mengkonversi gambar ke format base64
Server mengirimkan prompt dan gambar ke vision model via API
Server mengembalikan hasil analisis ke model coding

Fitur Utama

Vision API Integration: Menghubungkan model tanpa kemampuan vision dengan Vision Model
Multi-Image Support: Dapat menganalisis 1-10 gambar dalam satu permintaan
Flexible Prompts: Mendukung berbagai jenis permintaan (analisis UI, diagram, perbandingan dll)
OpenAI Compatible: Bekerja dengan berbagai provider yang kompatibel dengan OpenAI API
Comprehensive Error Handling: Penanganan error yang informatif dan user-friendly

Persyaratan

Node.js 18+ atau Bun 1.0+
API Key untuk vision model yang kompatibel dengan OpenAI

Instalasi

# Clone repository
git clone <repository-url>
cd vision-mcp

# Install dependencies
bun install

# Build project
bun run build

Konfigurasi

Server memerlukan environment variables berikut:

# Required
VISION_API_KEY=your_api_key_here

# Optional
VISION_API_BASE_URL=https://api.openai.com/v1  # Default: https://api.openai.com/v1
VISION_MODEL_NAME=gpt-4o                      # Default: gpt-4o
VISION_MAX_TOKENS=32000                       # Default: 32000

Provider Vision Model yang Didukung

Vision MCP Server dapat bekerja dengan berbagai provider yang kompatibel dengan OpenAI API:

OpenAI: Gunakan model seperti gpt-4o atau gpt-4-vision-preview
Custom Providers: Atur VISION_API_BASE_URL ke endpoint provider Anda
Local Models: Gunakan dengan server vLLM atau Ollama yang mendukung OpenAI-compatible API
Cloud Providers: Banyak cloud provider menyediakan endpoint yang kompatibel

Penggunaan dengan MCP Client

Konfigurasi untuk Claude Desktop

Tambahkan konfigurasi berikut ke claude_desktop_config.json:

{
  "mcpServers": {
    "vision-mcp": {
      "command": "bun",
      "args": ["/path/to/vision-mcp/dist/index.js"],
      "env": {
        "VISION_API_BASE_URL": "https://llm.chutes.ai/v1",
        "VISION_API_KEY": "your_api_key",
        "VISION_MODEL_NAME": "Qwen/Qwen3-VL-235B-A22B-Instruct",
        "VISION_MAX_TOKENS": "32000"
      }
    }
  }
}

Contoh Penggunaan

Setelah dikonfigurasi, Anda dapat meminta model untuk menganalisis gambar seperti:

"Analisis UI berikut dan berikan feedback tentang penggunaannya: /path/to/ui-screenshot.png"

"Bandingkan kedua desain berikut dan sebutkan perbedaannya: /path/to/design1.png /path/to/design2.png"

"Jelaskan alur yang ditunjukkan dalam diagram ini: /path/to/flow-diagram.png"

Contoh dengan Claude Desktop

Di chat Claude Desktop, Anda bisa menulis:

Tolong analisis screenshot ini berikan masukan untuk UX improvement: /home/user/screenshots/app-login.png

Claude akan menggunakan Vision MCP Server untuk menganalisis gambar dan memberikan feedback.

Format Gambar yang Didukung

JPG/JPEG
PNG
GIF
WebP
BMP

Batasan

Maksimum 10 gambar per permintaan
Ukuran file maksimum 10MB per gambar
Path gambar harus absolute path atau valid relative path
Memerlukan koneksi internet untuk komunikasi dengan API

Struktur Proyek

vision-mcp/
├── src/
│   ├── index.ts           # Entry point utama
│   ├── vision-tool.ts     # Implementasi vision tool
│   ├── vision-client.ts   # Client untuk OpenAI API
│   ├── file-handler.ts    # Utilitas pemrosesan file
│   └── types.ts           # Tipe dan schema
├── dist/                  # Output hasil build
├── package.json
├── tsconfig.json
└── README.md

Pengembangan

# Development mode dengan auto-reload
bun run dev

# Type checking
bun run typecheck

# Build untuk produksi
bun run build

# Jalankan server
bun start

Testing

Testing dengan Client

Gunakan file test client yang disediakan:

# Set environment variables
export VISION_API_KEY="your_api_key"

# Run test client
node examples/test_client.js

Langkah Testing

Pastikan environment variables terkonfigurasi

export VISION_API_BASE_URL="https://api.openai.com/v1"
export VISION_API_KEY="your_api_key"
export VISION_MODEL_NAME="gpt-4o"

Start MCP server
```
bun start
```
Test dengan MCP client (Claude Desktop, Cursor, dll)
Verifikasi vision tool tersedia dan berfungsi dengan gambar uji

Troubleshooting

Error Common Issues

"Image file not found": Pastikan path file benar dan file dapat diakses
"Authentication failed": Periksa VISION_API_KEY Anda
"Model not found": Pastikan VISION_MODEL_NAME valid untuk API Anda
"Rate limit exceeded": Tunggu beberapa saat sebelum mencoba lagi

Tips Tambahan

Gunakan absolute paths untuk menghindari masalah path resolution
Batas ukuran gambar: Optimalkan gambar besar sebelum menganalisis
Cache respons: Untuk gambar yang sama diulang, pertimbangkan cache
Monitoring: Monitor penggunaan API untuk menghindari rate limits

Lisensi

MIT License - lihat file LICENSE untuk detail.

Changelog

v2.0.0

Complete rewrite with improved architecture
Better error handling and validation
Enhanced type safety with Zod schemas
Improved file handling with support for multiple formats
Cleaner code structure and separation of concerns

v1.0.0

Initial release
Single vision tool implementation
Support for multiple image formats
OpenAI-compatible API integration
Comprehensive error handling