Servidor MCP ShortPixel

Servidor público HTTP MCP que expone la optimización de imágenes ShortPixel SPIO a agentes de IA (Cursor, Claude Desktop, VS Code, etc.).

Arquitectura

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)

Cada solicitud lleva la propia clave API de ShortPixel del usuario. El servidor MCP no almacena las claves de los usuarios; las reenvía a la API pública de SPIO.

Related MCP server: img-convert MCP Server

Requisitos

• Node.js 20+

• npm

Instalación (servidor)

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

Edita .env para la configuración del servidor (puerto, hosts permitidos, URL de la API upstream). No pongas claves de API de usuarios en el .env del servidor.

Ejecución

npm start

Endpoints:

Prueba rápida (curl)

Servidor activo, sin clave API:

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

Clave API presente (verificación simple):

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

Usa http:// (no https://) en el puerto 3000 a menos que TLS esté configurado en nginx.

Solicitud MCP (importante: los clientes HTTP Streamable deben aceptar tanto JSON como 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":{}}'

Autenticación

Envía la clave API de ShortPixel del usuario en cada solicitud MCP:

Authorization: Bearer <shortpixel_api_key>

Encabezado alternativo:

X-ShortPixel-Api-Key: <shortpixel_api_key>

Los usuarios sin clave pueden obtener una en shortpixel.com.

Configuración en Cursor (usuario final)

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

Reemplaza la URL con tu host desplegado durante el desarrollo (por ejemplo, http://localhost:3000/mcp).

Variables de entorno del servidor

Para desarrollo interno de ShortPixel, establece SHORTPIXEL_API_URL=https://devapi2.shortpixel.com/v2.

Registro de solicitudes

Los registros se envían a la salida estándar (pm2 logs / npm start).

Por defecto (LOG_FORMAT=text) — flujo narrativo que puedes seguir:

[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 mantiene solo los registros de aplicación de alto nivel y oculta los volcados de carga útil MCP.

Estructurado (LOG_FORMAT=json) — un objeto JSON por línea:

Las claves API están enmascaradas (****abcd). Las claves completas nunca se registran.

Nota: El mensaje del chat nunca llega a este servidor. El LLM (dentro del cliente MCP) convierte el texto del usuario en una llamada estructurada tools/call; el servidor solo ve los argumentos JSON-RPC y los asigna a la API de SPIO.

pm2 logs shortpixel-mcp
# or
npm start

Establece LOG_LEVEL=debug para tools/list y líneas HTTP adicionales.

Despliegue en servidor de desarrollo

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

Vuelve a subir package.json y package-lock.json después de cada cambio de dependencia. Si la compilación aún falla, ejecuta npm ci --include=dev (algunos servidores establecen NODE_ENV=production lo que omite las devDependencies).

Herramientas MCP disponibles

Argumentos de optimize_image_urls:

• urls (obligatorio): URLs de imágenes públicas para optimizar (máx. 100)

• lossy: Nivel de compresión (0 sin pérdida, 1 con pérdida, 2 brillante)

• wait: Segundos máximos de espera (0 para devolver inmediatamente, 1-30 para esperar)

• upscale: Factor de ampliación (0, 2, 3, 4)

• resize: Modo de redimensionamiento (0 ninguno, 1 exterior, 3 interior, 4 recorte inteligente)

• resize_width, resize_height: Dimensiones objetivo de redimensionamiento en píxeles

• cmyk2rgb: Convertir CMYK a RGB (1 sí, 0 no)

• keep_exif: Conservar metadatos EXIF (1 conservar, 0 eliminar)

• convertto: Valor de conversión (+webp, +avif, +webp|+avif, webp|avif, jpg, png, gif)

• bg_remove: Eliminación de fondo (1, URL de imagen, o #rrggbbxx)

• refresh: Forzar recuperación de fuente (1) o usar datos optimizados en caché (0)

• paramlist: Array de anulaciones por URL (debe coincidir con la longitud de urls)

• returndatalist: Cualquier array que se repite sin cambios en la respuesta

Estructura del proyecto

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

Convenciones de nomenclatura

Scripts