# vision-mcp

Serveur MCP (Model Context Protocol) d'**analyse d'images par modèles de vision LLM**, multi-fournisseur.

Analysez une ou plusieurs images à travers une interface MCP unifiée, avec le fournisseur de votre choix : OpenCode Go, OpenAI, Anthropic Claude, Google Gemini, ou tout endpoint compatible OpenAI (Ollama, vLLM, local).

## Fonctionnalités

- **4 outils MCP** : `analyze_image`, `analyze_images`, `list_providers`, `check_vision`
- **5 fournisseurs** : opencode, openai, anthropic, google, custom (compatible OpenAI)
- **Formats d'image** : PNG, JPG/JPEG, WEBP, GIF, BMP (par chemin de fichier absolu)
- **Logs sur stderr** (stdout réservé au protocole MCP)
- **Clés API via variables d'environnement** uniquement — aucun secret en dur

## Fournisseurs supportés

| Provider | Variable API Key | Base URL par défaut | Modèles vision |
|---|---|---|---|
| **opencode** | `OPENCODE_API_KEY` | `https://opencode.ai/zen/go/v1` | `qwen3.6-plus`, `qwen3.6-plus-free`, `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.1` |
| **openai** | `OPENAI_API_KEY` | `https://api.openai.com/v1` | `gpt-4o`, `gpt-4o-mini`, `gpt-4.5-preview`, `o1`, `o3-mini` |
| **anthropic** | `ANTHROPIC_API_KEY` | `https://api.anthropic.com/v1` | `claude-sonnet-4-20250514`, `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229`, `claude-3-haiku-20240307` |
| **google** | `GOOGLE_API_KEY` | `https://generativelanguage.googleapis.com/v1beta` | `gemini-2.5-flash-001`, `gemini-2.5-pro-001`, `gemini-2.0-flash-001`, `gemini-2.0-flash-lite-001` |
| **custom** | `CUSTOM_API_KEY` | `http://localhost:11434/v1` | N'importe quel modèle compatible OpenAI (Ollama, vLLM, local) |

> **Note :** certains modèles sont texte uniquement (ex. `deepseek-v4-flash`, `deepseek-v4-pro`) et ne supportent pas la vision.

## Prérequis

- **Python 3.10 ou supérieur**
- `pip` disponible

## Installation

```bash
git clone https://github.com/menoxz/vision-mcp.git
cd vision-mcp

# Environnement virtuel (recommandé)
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

# Dépendances
pip install -r requirements.txt
```

## Variables d'environnement

| Variable | Obligatoire | Description |
|---|---|---|
| `OPENCODE_API_KEY` | pour le provider `opencode` | Clé API OpenCode Go |
| `OPENCODE_BASE_URL` | non | URL de base (défaut : `https://opencode.ai/zen/go/v1`) |
| `OPENCODE_MODEL` | non | Modèle par défaut (défaut : `qwen3.6-plus`) |
| `OPENAI_API_KEY` | pour le provider `openai` | Clé API OpenAI |
| `OPENAI_MODEL` | non | Modèle par défaut (défaut : `gpt-4o`) |
| `ANTHROPIC_API_KEY` | pour le provider `anthropic` | Clé API Anthropic |
| `ANTHROPIC_MODEL` | non | Modèle par défaut (défaut : `claude-sonnet-4-20250514`) |
| `GOOGLE_API_KEY` | pour le provider `google` | Clé API Google Gemini |
| `GOOGLE_MODEL` | non | Modèle par défaut (défaut : `gemini-2.5-flash-001`) |
| `CUSTOM_API_KEY` | pour le provider `custom` | Clé API de l'endpoint personnalisé |
| `CUSTOM_BASE_URL` | non | URL de base (défaut : `http://localhost:11434/v1`) |
| `CUSTOM_MODEL` | non | Modèle par défaut (défaut : `qwen2.5-vl-72b-instruct`) |

## Configuration MCP (opencode.json)

Ajoutez ce bloc dans la section `"mcp"` de votre `opencode.json` (CLI ou VSCode) :

```json
{
  "mcp": {
    "vision-mcp": {
      "type": "local",
      "command": [
        "python",
        "C:/chemin/vers/vision-mcp/server.py"
      ],
      "environment": {
        "PYTHONIOENCODING": "utf-8",
        "OPENCODE_API_KEY": "sk-...",
        "OPENCODE_BASE_URL": "https://opencode.ai/zen/go/v1",
        "OPENCODE_MODEL": "qwen3.6-plus"
      },
      "enabled": true
    }
  }
}
```

Redémarrez ensuite opencode (ou `/reload`).

## Outils exposés

| Outil | Description |
|---|---|
| `analyze_image(image_path, prompt, provider, model)` | Analyse une image avec un prompt texte |
| `analyze_images(image_paths, prompt, provider, model)` | Analyse/comparaison de plusieurs images (min. 2) |
| `list_providers()` | Liste les fournisseurs et leur état de configuration |
| `check_vision(provider, model)` | Teste un fournisseur/modèle avec une image de test (cercle rouge) |

### Exemples

```
analyze_image(image_path="C:/screenshot.png",
              prompt="Décris l'interface utilisateur.",
              provider="opencode")

analyze_images(image_paths=["C:/img1.png", "C:/img2.png"],
               prompt="Compare ces deux designs.",
               provider="openai", model="gpt-4o")

list_providers()
check_vision(provider="opencode")
```

## Dépannage

| Problème | Solution |
|---|---|
| `No API key configured` | Définir la variable d'environnement `<PROVIDER>_API_KEY` |
| Timeout (120 s) | Image trop grande — redimensionner (max ~20 Mo) |
| 400 Bad Request | Le modèle ne supporte pas la vision |
| Aucune sortie | Les logs sont sur **stderr** ; stdout est réservé au protocole MCP |

## Licence

Distribué sous licence [MIT](LICENSE) — Copyright (c) 2026 Jean-Luc KOUMAGLO / menoxz.