ShortPixel MCP Server

Публичный HTTP MCP-сервер, который предоставляет оптимизацию изображений ShortPixel SPIO AI-агентам (Cursor, Claude Desktop, VS Code и др.).

Архитектура

AI client (Cursor, Claude, …)
    │
    │  MCP over HTTPS (Streamable HTTP)
    ▼
https://mcp.shortpixel.com/mcp
    │
    │  user's API key in Authorization header
    ▼
ShortPixel SPIO API (api.shortpixel.com)

Каждый запрос содержит собственный API-ключ ShortPixel пользователя. MCP-сервер не хранит ключи пользователей — он передает их в публичный SPIO API.

Related MCP server: img-convert MCP Server

Требования

• Node.js 20+

• npm

Установка (сервер)

npm ci
npm run build
cp .env.example .env

Отредактируйте .env для настроек сервера (порт, разрешенные хосты, URL вышестоящего API). Не помещайте пользовательские API-ключи в .env сервера.

Запуск

npm start

Эндпоинты:

Быстрый тест (curl)

Сервер запущен, без API-ключа:

curl http://mcp.shortpixel.com:3000/health

API-ключ присутствует (простая проверка):

curl -i -H "Authorization: Bearer YOUR_API_KEY" http://mcp.shortpixel.com:3000/ping

Используйте http:// (не https://) на порту 3000, если TLS не настроен на nginx.

MCP-запрос (важно: Streamable HTTP-клиенты должны принимать как JSON, так и SSE):

curl -s -N -X POST http://mcp.shortpixel.com:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Аутентификация

Отправляйте API-ключ ShortPixel пользователя в каждом MCP-запросе:

Authorization: Bearer <shortpixel_api_key>

Альтернативный заголовок:

X-ShortPixel-Api-Key: <shortpixel_api_key>

Пользователи без ключа могут получить его на shortpixel.com.

Настройка Cursor (конечный пользователь)

{
  "mcpServers": {
    "shortpixel": {
      "url": "https://mcp.shortpixel.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SHORTPIXEL_API_KEY"
      }
    }
  }
}

Замените URL на ваш развернутый хост во время разработки (например, http://localhost:3000/mcp).

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

Для внутренней разработки ShortPixel установите SHORTPIXEL_API_URL=https://devapi2.shortpixel.com/v2.

Логирование запросов

Логи выводятся в stdout (pm2 logs / npm start).

По умолчанию (LOG_FORMAT=text) — повествовательный поток, которому можно следовать:

[2026-06-30 15:01:53] [1/5] → CLIENT | HTTP POST /mcp | JSON-RPC request: "initialize" (client connects) | id: 0
           {
             "jsonrpc": "2.0",
             "method": "initialize",
             "id": 0,
             "params": { ... }
           }
[2026-06-30 15:01:53] [1/5] ← SERVER | HTTP POST /mcp 200 | JSON-RPC response: "initialize" (client connects)
[2026-06-30 15:01:53] [2/5] → CLIENT | HTTP POST /mcp | JSON-RPC request: "notifications/initialized" (session ready, no response body expected) | id: null
[2026-06-30 15:01:53] [2.5/5] → CLIENT | HTTP POST /mcp | JSON-RPC request: "tools/list" (client asks which tools exist) | id: 1
[2026-06-30 15:01:53] [2.5/5] ← SERVER | HTTP POST /mcp 200 | JSON-RPC response: "tools/list" (client asks which tools exist) | tools discovered: optimize_image_urls
[2026-06-30 15:02:18] [3/5] → CLIENT | HTTP POST /mcp | JSON-RPC request: "tools/call" (client runs a tool) | id: 2 | tool: "optimize_image_urls"
[2026-06-30 15:02:18] [4/5] MCP → SPIO API: POST reducer.php (args mapped to SPIO payload) | ...
[2026-06-30 15:02:35] [5/5] MCP ← SPIO API: Success | reduction: 27.41% | optimized: http://api.shortpixel.com/f/...-lossy.jpg | original: ...
[2026-06-30 15:02:35] [3/5] ← SERVER | HTTP POST /mcp 200 | JSON-RPC response: "tools/call" (client runs a tool) | tool: optimize_image_urls
           { "jsonrpc": "2.0", "id": 2, "result": { ... } }
[2026-06-30 15:02:35]     ✓ round-trip done (16.3s)

LOG_MCP_PROTOCOL=false оставляет только высокоуровневые логи приложения и скрывает дампы MCP-полезных нагрузок.

Структурированный (LOG_FORMAT=json) — один JSON-объект на строку:

API-ключи маскируются (****abcd). Полные ключи никогда не логируются.

Примечание: Подсказка чата никогда не достигает этого сервера. LLM (внутри MCP-клиента) преобразует текст пользователя в структурированный tools/call; сервер видит только JSON-RPC аргументы и сопоставляет их с SPIO API.

pm2 logs shortpixel-mcp
# or
npm start

Установите LOG_LEVEL=debug для tools/list и дополнительных HTTP-строк.

Развертывание на dev-сервере

cd /xxx/mcp.shortpixel.com
npm ci
npm run build
cp .env.example .env
# set ALLOWED_HOSTS and PORT, then run behind nginx with TLS
npm start

Повторно загрузите package.json и package-lock.json после каждого изменения зависимостей. Если сборка все еще не удается, выполните npm ci --include=dev (некоторые серверы устанавливают NODE_ENV=production, что пропускает devDependencies).

Доступные MCP-инструменты

Аргументы optimize_image_urls:

• urls (обязательный): Публичные URL изображений для оптимизации (макс. 100)

• lossy: Уровень сжатия (0 без потерь, 1 с потерями, 2 глянцевый)

• wait: Макс. время ожидания в секундах (0 для немедленного возврата, 1-30 для ожидания)

• upscale: Коэффициент увеличения (0, 2, 3, 4)

• resize: Режим изменения размера (0 нет, 1 внешний, 3 внутренний, 4 умная обрезка)

• resize_width, resize_height: Целевые размеры изменения в пикселях

• cmyk2rgb: Преобразование CMYK в RGB (1 да, 0 нет)

• keep_exif: Сохранение EXIF-метаданных (1 сохранить, 0 удалить)

• convertto: Значение конвертации (+webp, +avif, +webp|+avif, webp|avif, jpg, png, gif)

• bg_remove: Удаление фона (1, URL изображения или #rrggbbxx)

• refresh: Принудительная повторная загрузка источника (1) или использование кэшированных оптимизированных данных (0)

• paramlist: Массив переопределений для каждого URL (должен соответствовать длине urls)

• returndatalist: Любой массив, возвращаемый без изменений в ответе

Структура проекта

src/index.ts                    HTTP server entry point
src/http/auth.ts                API key extraction from requests
src/mcp/create-mcp-server.ts    Per-request MCP server factory
src/clients/spio-api-client.ts  ShortPixel SPIO HTTP client
src/tools/spio-tools.ts         MCP tools
src/http/request-log-middleware.ts HTTP request logging
src/logging/request-logger.ts    Structured JSON logger
src/logging/mcp-protocol-log.ts  MCP protocol payload capture/normalize

Соглашения об именовании

Скрипты