Vision MCP Server

Сервер Model Context Protocol (MCP), который даёт возможность понимания изображений агентам, подключённым к немультимодальным моделям (DeepSeek, старые GPT-4, локальные маленькие модели и т. д.): агент передаёт изображение MCP-инструменту, сервер вызывает vision-модель и возвращает текст.

Поддерживает основных провайдеров в Китае и США, а также любую OpenAI-совместимую конечную точку. Официальные SDK в первую очередь, абстракция до реализации, добавление провайдеров без вторжения в код.

中文文档见 README.zh-CN.md

Возможности

• 4 инструмента: analyze_image / describe_image / ocr_image / list_providers, все возвращают обычный Markdown-текст

• 13 встроенных провайдеров: OpenAI / Anthropic / Google Gemini / Qwen (DashScope) / Zhipu / Doubao (Volcengine) / ERNIE (Qianfan) / StepFun / Ollama / Alibaba Bailian / SiliconFlow / OpenRouter / собственная OpenAI-совместимая конечная точка

• Три способа передачи изображения: локальный путь / http(s) URL / base64 (data URI или сырой base64), автоматическое определение

• Трёхуровневая цепочка резервирования: официальный SDK → OpenAI-совместимая конечная точка → нативный fetch (см. SPEC §1)

• Без состояния: каждый вызов независим; изображения и результаты никогда не кэшируются; ключи читаются только из переменных окружения

Related MCP server: vision-mcp

Быстрый старт

Вариант A: npx (опубликовано в npm, репозиторий не нужен)

npx -y @inferai/vision-mcp

Вариант B: локальная сборка

git clone <repo> && cd vision-mcp
pnpm install
pnpm build
node dist/index.js

Примеры конфигурации MCP (stdio)

Сервер использует транспорт stdio: MCP-клиент запускает процесс и обменивается JSON-RPC-сообщениями через stdin/stdout. Настройте его там, где ваш клиент определяет MCP-серверы:

• Claude Code: .mcp.json на уровне проекта или ~/.claude.json на уровне пользователя (ключ mcpServers)

• Claude Desktop: claude_desktop_config.json

• Любой MCP-клиент (Cursor, собственные агенты и т. д.): та же структура

Версия npx (доступна после публикации пакета):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": ["-y", "@inferai/vision-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "DASHSCOPE_API_KEY": "sk-..."
      }
    }
  }
}

Локальная разработка (скорректируйте путь; --env-file-if-exists=.env нативно загружает .env):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "node",
      "args": ["--env-file-if-exists=.env", "/absolute/path/to/vision-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

С аргументами запуска (переопределение значений провайдера по умолчанию через argv, см. ниже):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@inferai/vision-mcp",
        "--default-provider=dashscope",
        "--siliconflow-api-key=sk-...",
        "--siliconflow-model=Qwen/Qwen2.5-VL-7B-Instruct"
      ],
      "env": {
        "DASHSCOPE_API_KEY": "sk-..."
      }
    }
  }
}

Примечания по stdio:

• stdout несёт только протокол MCP — сервер никогда не выводит туда логи; диагностика идёт в stderr

• клиент управляет жизненным циклом процесса (запуск при старте, завершение при выходе); демон не нужен

• первый запуск npx скачивает пакет и может занять несколько секунд

• переменные окружения также могут приходить из окружения оболочки, если клиент его наследует (блок env не нужен)

Отладка с MCP Inspector:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js --xxx-api-key=xxx --xxx2-api-key=xxx

Настройка переменных

1. Блок env в конфигурации MCP (рекомендуется, наиболее надёжно на всех платформах) — запишите переменные в объект env выше

2. Файл .env (локальная разработка) — скопируйте .env.example в .env, заполните его, затем node --env-file-if-exists=.env dist/index.js (нативный Node 22, dotenv не нужен)

3. Экспорт в оболочке — export OPENAI_API_KEY=sk-xxx и запуск

Провайдеры без ключей отображаются как недоступные в list_providers и сообщают о недостающей переменной при вызове.

Публикация (до того, как заработает npx)

pnpm publish          # or pnpm release (changeset flow)

Переменные окружения

Для каждого провайдера API_KEY, BASE_URL и MODEL поддерживают переопределение через окружение (соглашение: <PROVIDER_PREFIX>_API_KEY / <PROVIDER_PREFIX>_BASE_URL / <PROVIDER_PREFIX>_MODEL):

? = необязательно (есть встроенное значение по умолчанию); * = обязательно.

Глобальная конфигурация:

Цепочка резервирования

Когда доступно несколько провайдеров, вызовы идут по цепочке приоритетов: настроенный по умолчанию → список VISION_MCP_PROVIDER_PRIORITY → порядок таблицы (недоступные провайдеры пропускаются).

• каждый провайдер повторяется до VISION_MCP_MAX_RETRIES раз при ошибках провайдера (сбои вышестоящего сервиса, таймауты)

• после исчерпания повторов провайдера пробуется следующий доступный провайдер в цепочке, до VISION_MCP_MAX_FALLBACKS резервных переходов

• только ошибки провайдера вызывают повтор/резервирование; ошибки конфигурации или изображения завершаются сразу

• явно запрошенный аргумент provider пробуется только сам (без резервирования)

• при полном отказе в ошибке перечисляются все испробованные провайдеры и их последние ошибки

Также доступно через argv: --provider-priority=..., --max-retries=N, --max-fallbacks=N (имеют приоритет над переменными окружения).

Аргументы запуска MCP (argv)

Для каждого провайдера apiKey / baseUrl / model можно переопределить через аргументы запуска (приоритет выше переменных окружения), формат --<provider>-<field>:

node dist/index.js \
  --openai-api-key=sk-xxx \
  --openai-base-url=https://my-gateway.example.com/v1 \
  --openai-model=gpt-4o-mini \
  --dashscope-api-key=sk-xxx \
  --default-provider=dashscope

• Глобальные: --default-provider <имя> / --default-model <имя>

• Для каждого провайдера: --<provider>-api-key, --<provider>-base-url, --<provider>-model (работает и форма с =, и с пробелом)

• Любая OpenAI-совместимая сторонняя служба: подключение одной строкой через --openai-compat-base-url + --openai-compat-api-key + --openai-compat-model; или укажите base-url любого встроенного провайдера на зеркало/прокси

Приоритет: аргументы инструмента provider/model > аргументы запуска (для провайдера > глобальное значение по умолчанию) > переменные окружения > встроенные значения провайдера по умолчанию.

Инструменты

image принимает: локальный путь / http(s):// URL / data: URI / сырой base64, автоматическое определение.

Примечание по безопасности: загрузка URL защищена от SSRF — каждый переход (включая редиректы) проверяется, а URL, разрешающиеся в loopback-, приватные или link-local-адреса, блокируются (в ошибке есть подсказка с объяснением причины).

Интеграция провайдеров (трёхуровневая цепочка резервирования)

Добавление провайдера: для конечных точек, совместимых с OpenAI, добавьте одну строку в RULES в src/core/config.ts и одно сопоставление в фабричную таблицу в src/index.ts — ноль нового кода. Реализации официального SDK или нативного fetch: см. SPEC §1.

Разработка

pnpm check        # biome checks
pnpm test         # rstest unit tests (injected mocks, no network)
pnpm build        # rslib build

Дымовые тесты с реальными вызовами (выполняются только для провайдеров, для которых настроены ключи; в противном случае пропускаются):

OPENAI_API_KEY=sk-... pnpm exec rstest tests/e2e

Архитектура

src/
├── index.ts            # Entry: composition root, stdio startup
├── core/               # Abstraction: interfaces / image loading / config / registry
├── providers/          # Adapters: official SDK or compatible endpoints, protocol conversion only
└── server/tools.ts     # MCP tool layer: zod validation + error mapping

Полная спецификация: SPEC.md.