opencode-eyes-nvidia 👁️

MCP server that provides image description capability using NVIDIA NIM hosted API (https://integrate.api.nvidia.com/v1) with the MiniMax-M3 multimodal model.

다중 모달 기능이 없는 모델에 **"눈"**을 제공합니다. 이미지를 입력하면 상세한 이미지 설명을 얻을 수 있습니다.

기능

Related MCP server: vision-mcp

멀티모달 모델

기본 모델은 minimaxai/minimax-m3(텍스트/이미지/비디오 입력 → 텍스트 출력, 1M 컨텍스트, 추론 지원)입니다. NVIDIA_MODEL 또는 describe_image의 model 매개변수로 전환할 수 있습니다:

환경 변수

* Key를 하나 이상 구성해야 합니다: NVIDIA_API_KEY, NVIDIA_API_KEYS 또는 NVIDIA_API_KEY_1..N 중 하나면 되며, 동시에 구성할 수 있습니다(중복 제거 후 병합).

Key 폴링(다중 Key 자동 전환)

여러 API Key를 구성할 수 있습니다: 요청은 순서대로 사용되며, 오류가 발생하면 자동으로 다음 Key로 전환됩니다. 원래 Key는 삭제되지 않으며, 대기열 끝으로 이동하여 할당량이 새로 고쳐질 때까지 기다렸다가 다시 사용됩니다. 전 과정이 자동으로 재시도되므로 수동 개입이 필요 없습니다.

작동 방식:

1. 시작 시 모든 Key를 하나의 대기열로 병합합니다(중복 제거, NVIDIA_API_KEY → NVIDIA_API_KEYS → NVIDIA_API_KEY_1..N 순서).

2. 요청은 기본적으로 대기열 맨 앞의 Key를 사용합니다.

3. 재시도 가능한 오류(HTTP 401 / 403 / 404 / 408 / 429 / 5xx 또는 연결 시간 초과)가 발생하면: 대기열 맨 앞의 Key를 맨 뒤로 이동하고, NVIDIA_ROTATION_BACKOFF초 후 다음 Key로 재시도합니다.

4. 모든 Key를 순환한 후에도(총 NVIDIA_ROTATION_MAX_RETRIES회 시도) 성공하지 못하면 마지막 오류를 발생시킵니다.

5. 대기열 상태는 여러 호출 간에 유지됩니다. 제한된 Key는 뒤로 밀리며, 다음 차례가 되면 할당량이 새로 고쳐져 있을 때가 많습니다.

예시:

# 方式一：逗号分隔多个 Key
set NVIDIA_API_KEYS=nvapi-key-1,nvapi-key-2,nvapi-key-3

# 方式二：编号 Key
set NVIDIA_API_KEY_1=nvapi-key-1
set NVIDIA_API_KEY_2=nvapi-key-2

# 方式三：单个 Key（向后兼容）
set NVIDIA_API_KEY=nvapi-key-1

OpenCode 구성에서 MCP 서비스로 환경 변수를 전달합니다:

{
  "mcp": {
    "opencode-eyes-nvidia": {
      "type": "local",
      "command": ["python", "-m", "opencode_eyes_nvidia"],
      "enabled": true,
      "timeout": 120000,
      "environment": {
        "NVIDIA_API_KEYS": "{env:NVIDIA_API_KEYS}"
      }
    }
  }
}

설치

pip install -r requirements.txt

또는 패키지로 설치:

pip install .

실행

# 设置环境变量（Windows，至少一种）
set NVIDIA_API_KEY=nvapi-你的key
# 或 set NVIDIA_API_KEYS=nvapi-key-1,nvapi-key-2

# 启动服务
python -m opencode_eyes_nvidia

OpenCode에서 구성

{
  "mcp": {
    "opencode-eyes-nvidia": {
      "type": "local",
      "command": ["python", "-m", "opencode_eyes_nvidia"],
      "enabled": true,
      "timeout": 120000,
      "environment": {
        "NVIDIA_API_KEYS": "{env:NVIDIA_API_KEYS}",
        "NVIDIA_API_KEY": "{env:NVIDIA_API_KEY}"
      }
    }
  }
}

수동 테스트

opencode를 시작하지 않고 stdio를 통해 직접 검증:

$env:NVIDIA_API_KEY = "nvapi-xxx"
python -m opencode_eyes_nvidia

그런 다음 다른 터미널에서 MCP JSON-RPC 메시지를 보냅니다. 예:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.0.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"describe_image","arguments":{"image_path":"C:/path/to/photo.jpg"}}}

opencode-eyes와의 차이점

• API를 StepFun에서 NVIDIA NIM(https://integrate.api.nvidia.com/v1)으로 변경

• 기본 모델을 step-3.7-flash에서 MiniMax-M3(minimaxai/minimax-m3)로 변경

• list_vision_models 도구 및 다중 모델 전환 기능 추가

• MiniMax-M3의 thinking_mode 추론 제어 지원

• 다중 API Key 폴링 지원: 오류 발생 시 자동으로 다음 Key로 전환하고, 원래 Key는 대기열 끝으로 이동하여 할당량 새로고침을 기다립니다.

라이선스