ShortPixel Image Optimizer

ShortPixel MCP 服务

公共 HTTP MCP 服务，向 AI Agent（Cursor、Claude Desktop、VS Code 等）提供 ShortPixel SPIO 图像优化功能。

架构

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)

每个请求都携带用户自己的 ShortPixel API 密钥。MCP 服务不会存储用户密钥，而是将其转发至公共 SPIO API。

要求

• Node.js 20+
• npm

安装（服务端）

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

编辑 .env 配置服务设置（端口、允许的主机、上游 API URL）。请勿将用户 API 密钥放入服务端 .env。

运行

npm start

端点：

路径	方法	描述
/health	GET	健康检查（无需 API 密钥）
/ping	GET	身份验证检查 — 如果存在 API 密钥标头，则返回 ok
/mcp	POST	MCP Streamable HTTP 端点

快速测试（curl）

服务已启动，无 API 密钥：

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

存在 API 密钥（简单检查）：

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

除非已在 nginx 上配置 TLS，否则请在端口 3000 上使用 http://（而非 https://）。

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":{}}'

身份验证

每次 MCP 请求都发送用户的 ShortPixel API 密钥：

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）。

服务端环境变量

变量	必需	默认值	描述
PORT	否	3000	HTTP 监听端口
ALLOWED_HOSTS	否	—	以逗号分隔的 Host 标头允许列表（生产环境推荐）
SHORTPIXEL_API_URL	否	https://api.shortpixel.com/v2	上游 SPIO API 基础 URL
SHORTPIXEL_PLUGIN_VERSION	否	MCP01	发送至 SPIO 的插件版本
LOG_LEVEL	否	info	日志详细程度：debug、info、warn、error
LOG_FORMAT	否	text	text = 易读的文本行；json = 结构化 JSON
LOG_MCP_PROTOCOL	否	true	记录传入和传出的 MCP JSON-RPC 载荷

ShortPixel 内部开发时，设置 SHORTPIXEL_API_URL=https://devapi2.shortpixel.com/v2。

请求日志

日志输出到 stdout；shortpixel-mcp systemd 服务会将其重定向到 /var/log/shortpixel/mcp.log（在本地运行时，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 对象：

事件	发生时机
http_request	每个请求（方法、路径、状态、耗时、MCP 方法/工具）
spio_request	发往 SPIO reducer.php 的调用
spio_response	SPIO 结果摘要（状态、改进百分比）
mcp_auth_missing	请求未携带 API 密钥

API 密钥会被掩码处理（****abcd）。绝不会记录完整密钥。

注意： 聊天提示词不会到达此服务。LLM（位于 MCP 客户端内）会将用户文本转换为结构化的 tools/call；服务端只能看到 JSON-RPC 参数，并将其映射到 SPIO API。

tail -f /var/log/shortpixel/mcp.log
# or, running locally
npm start

设置 LOG_LEVEL=debug 可查看 tools/list 和额外的 HTTP 日志行。

部署

以 shortpixel-mcp systemd 服务运行（单元文件位于 /etc/systemd/system/shortpixel-mcp.service），该服务直接运行 node dist/index.js（不使用 pm2），并从项目目录中的 .env 读取环境变量（EnvironmentFile=）。

cd /web/mcp.shortpixel.com   # liveVPS; a separate host from the rest of the PHP stack
npm ci
npm run build
# edit .env directly on the server (not deployed - gitignored)
sudo systemctl restart shortpixel-mcp
sudo systemctl status shortpixel-mcp

每次依赖项变更后，重新上传 package.json 和 package-lock.json。如果构建仍然失败，请运行 npm ci --include=dev（某些服务器会设置 NODE_ENV=production，从而跳过 devDependencies）。

可用的 MCP 工具

工具	描述
optimize_image_urls	通过 SPIO reducer API 优化一个或多个公开图片 URL

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

命名约定

类型	风格	示例
文件	kebab-case	spio-api-client.ts
类	PascalCase	SpioApiClient
方法	camelCase	optimizeUrls

脚本

命令	描述
npm run build	将 TypeScript 编译到 dist/
npm start	运行 HTTP MCP 服务
npm run dev	使用 tsx 运行（无需构建步骤）