SmallPict LogoSmallPict

Model Context Protocol (MCP) AI 集成

将 SmallPict 图像优化能力直接赋能给 AI 智能体：Claude Desktop, Cursor, Google Antigravity, OpenCode, Codex 与 Windsurf。

SmallPict Model Context Protocol (MCP) 服务器

SmallPict MCP Server (@smallpict/mcp) 严格遵循开放的 Model Context Protocol 协议规范，为大语言模型（LLMs）与自动化 AI 编程智能体提供原生图像检测、优化、格式转换与缓存管理工具。

交互式系统架构流程图

端到端图像处理与边缘 CDN 分发架构流程

从客户端发起上传到全球 Cloudflare Enterprise 边缘交付，全流程平均耗时低于 50ms。

源站请求

客户端应用

WordPress / SDK / API

携带 HMAC-SHA256 签名与 UUID v4 幂等键安全上传原始图像二进制流。

阶段 1 就绪
缓存与分发

Cloudflare 边缘 CDN

全球边缘节点 PoP

就近查找全球边缘缓存。命中的缓存直接在 <20ms 内完成全球极速交付。

阶段 2 就绪
鉴权与隔离

SmallPict Go 网关

AWS Lambda / API Gateway

严格验证 HMAC 签名凭据，校验账户配额并按 customer_id 隔离访问范围。

阶段 3 就绪
深度转码

libvips SIMD 转码集群

超高速 C 语言核心引擎

多线程硬件级向量化转码至 AVIF & WebP，肉眼画质零损失，平均体积节省约 88%。

阶段 4 就绪
持久同步

S3 存储与管道同步

全球对象存储

持久化存储处理结果，清理过期缓存标签，并反向预热 Cloudflare 边缘节点。

阶段 5 就绪
零数据拦截：全链路 HMAC 身份鉴权与 SHA256 完整性校验
转码引擎： libvips SIMD·处理延迟： <50ms

⚡ 核心设计亮点

  • 全生态通用支持： 完美适配 Claude for Desktop、Cursor IDE、Google Antigravity (AGY)、OpenCode、Windsurf、Cline / Roo Code 等所有支持 MCP 的环境。
  • 无需本地编译： 借助 Node.js 18+ 直接通过 npx -y @smallpict/mcp 即刻运行。
  • 安全隔离架构： 进程间基于标准输入输出 (stdio) 通信，所有内部日志强制输出到 stderr，杜绝破坏 JSON-RPC 通信流。
  • 双环境支持： 既支持正式生产私钥 (sp_live_...)，也支持免费沙箱密钥 (sp_test_...) 进行零额度测试。

🛠️ 内置可用 MCP 工具清单

智能体成功连接后，将自动解锁以下三项高生产力工具：

1. smallpict_optimize_image

压缩本地图像文件或公网图片 URL，并转码为下一代高效格式（WebP, AVIF），最高缩减 88% 体积。

参数名类型是否必填参数描述
image_pathstring是本地绝对/相对图片路径，或公网 HTTP/HTTPS 图片地址。
target_formatstring否目标格式：webp（默认）, avif, jpg, 或 png。
qualitynumber否压缩质量 1 至 100（默认：80）。
modestring否优化模式：balanced（默认）, aggressive, ultra, 或 lossless。
max_long_edge_pxnumber否等比例缩放：限制图片最长边像素。
output_pathstring否自定义本地输出路径（默认保存在原目录并在文件名添加后缀）。

2. smallpict_get_quota

查询当前 SmallPict 账户的订阅状态、月度总配额上限、已用流量与剩余可用额度。

参数名类型是否必填参数描述
(无参数)--自动携带当前 API Key 发起配额健康度遥测。

3. smallpict_purge_cdn_cache

在更新资源后，实时清除 Cloudflare 全球边缘 CDN 缓存。

参数名类型是否必填参数描述
urlsstring[]否需要立即清除缓存的目标图片 URL 列表或 CDN 相对路径。
purge_allboolean否是否清理整个关联域名的全量缓存（默认：false）。

🚀 多端智能体配置指南

1. Claude for Desktop

在您的 claude_desktop_config.json 配置文件中添加服务定义：

  • macOS 系统： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows 系统： %APPDATA%\Claude\claude_desktop_config.json
  • Linux 系统： ~/.config/Claude/claude_desktop_config.json
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

重启 Claude Desktop，右下角将出现 🔨 锤子工具图标，证明 SmallPict 工具已就绪。

2. Cursor IDE

方式 A：Cursor 全局设置

  1. 打开 Cursor Settings (Cmd + , 或 Ctrl + ,)。
  2. 依次进入 Features → MCP Servers。
  3. 点击 + Add New MCP Server：
    • Name: smallpict
    • Type: command
    • Command: npx -y @smallpict/mcp
    • Environment Variables: SMALLPICT_API_KEY=sp_live_YOUR_API_KEY

方式 B：项目级配置 (.cursor/mcp.json)

在项目根目录下创建 .cursor/mcp.json 文件：

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

3. Google Antigravity (AGY)

在使用 Antigravity 多智能体协同环境时，将 SmallPict MCP 服务写入 ~/.gemini/antigravity/mcp/smallpict/mcp.json 或项目级工作区配置中：

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

现在，Antigravity 子智能体可以在项目前端重构或构建流水线中全自动压缩静态资源。

4. VS Code (Cline / Roo Code)

  1. 打开 Cline 面板，点击 MCP Servers 选项卡。
  2. 选择 Configure MCP Servers（打开 cline_mcp_settings.json）。
  3. 添加以下配置：
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      },      "disabled": false,      "autoApprove": [        "smallpict_get_quota",        "smallpict_optimize_image"      ]    }  }}

5. Windsurf (Codeium)

编辑 ~/.codeium/windsurf/mcp_config.json 文件：

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{  "mcpServers": {    "smallpict": {      "command": "npx",      "args": [        "-y",        "@smallpict/mcp"      ],      "env": {        "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY"      }    }  }}

💬 实用 AI 对话指令范例

配置完成后，您无需编写脚本，直接用日常自然语言即可指挥智能体：

批量优化本地图片

"AI，帮我检查 public/images/ 目录下的所有 PNG 和 JPEG 图片，将它们转为质量 80 的 WebP 格式，并输出一张表格告诉我节省了多少字节。"

查询账户剩余配额

"查一下我这个月还剩多少 SmallPict 图片处理配额，我准备批量处理一批轮播大图。"

边缘 CDN 缓存快速清理

"我刚刚在 S3 上更新了 hero-banner.jpg，请帮我调用 SmallPict CDN 接口清理该图片的全球边缘缓存。"