Giao thức Model Context Protocol (MCP) cho AI
Kết nối trực tiếp các công cụ tối ưu hóa hình ảnh SmallPict với AI Agent: Claude Desktop, Cursor, Google Antigravity, OpenCode, Windsurf.
Máy chủ Model Context Protocol (MCP) SmallPict
SmallPict MCP Server (@smallpict/mcp) triển khai tiêu chuẩn mở Model Context Protocol, mang đến cho các mô hình ngôn ngữ lớn (LLM) và các AI Agent lập trình các công cụ native để kiểm tra, nén, chuyển đổi và quản lý tài nguyên hình ảnh trực tiếp trong luồng làm việc.
End-to-End Image Processing & Edge CDN Flow
Sub-50ms image optimization lifecycle from client upload to Cloudflare Enterprise edge delivery.
Client Application
WordPress / SDK / API
Uploads raw image binary with HMAC-SHA256 signature and UUID v4 idempotency key.
Cloudflare Edge CDN
Global Edge PoPs
Checks global edge cache. On cache HIT, delivers AVIF/WebP in <20ms worldwide.
SmallPict Go Gateway
AWS Lambda / API Gateway
Validates HMAC credentials, verifies quota limits, and scopes access to customer_id.
libvips SIMD Worker
High-Speed C-Engine
Multi-threaded quantization transcode to AVIF & WebP with 0 visual loss and ~88% compression.
S3 Pipeline & Storage
Global Object Store
Stores optimized output, invalidates outdated cache tags, and hydrates Cloudflare Edge.
⚡ Các ưu điểm nổi bật
- Tương thích toàn diện với nhiều AI Agent: Hoạt động mượt mà với Claude for Desktop, Cursor IDE, Google Antigravity (AGY), OpenCode, Windsurf, Cline / Roo Code và bất kỳ môi trường nào hỗ trợ MCP.
- Không cần biên dịch cục bộ: Chạy ngay lập tức thông qua lệnh
npx -y @smallpict/mcpvới môi trường Node.js 18+. - Kiến trúc bảo mật tiêu chuẩn: Giao tiếp hoàn toàn qua luồng vào/ra chuẩn (
stdio) và toàn bộ nhật ký lỗi được chuyển tớistderrđể tránh gây nhiễu luồng dữ liệu JSON-RPC. - Hỗ trợ hai môi trường: Tương thích với cả khóa chính thức (
sp_live_...) và khóa sandbox miễn phí (sp_test_...).
🛠️ Danh sách công cụ MCP khả dụng
Sau khi kết nối, AI Agent của bạn sẽ tự động có quyền truy cập vào 3 công cụ sau:
1. smallpict_optimize_image
Nén và chuyển đổi các tệp hình ảnh cục bộ hoặc URL ảnh trên mạng sang định dạng thế hệ mới (WebP, AVIF) với mức giảm dung lượng lên đến 88%.
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
image_path | string | Có | Đường dẫn tệp cục bộ (tuyệt đối/tương đối) hoặc URL hình ảnh công khai. |
target_format | string | Không | Định dạng đích: webp (mặc định), avif, jpg, hoặc png. |
quality | number | Không | Mức chất lượng nén từ 1 đến 100 (mặc định: 80). |
mode | string | Không | Chế độ nén: balanced (mặc định), aggressive, ultra, hoặc lossless. |
max_long_edge_px | number | Không | Giới hạn độ dài cạnh lớn nhất của ảnh (giữ nguyên tỷ lệ khung hình). |
output_path | string | Không | Đường dẫn lưu tệp kết quả (mặc định lưu cùng thư mục với đuôi mở rộng mới). |
2. smallpict_get_quota
Truy vấn thông tin gói dịch vụ hiện tại, hạn ngạch xử lý hàng tháng, dung lượng đã dùng và số byte còn lại của tài khoản.
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| (Không tham số) | - | - | Tự động sử dụng khóa API đã cấu hình để truy vấn thông số tài khoản. |
3. smallpict_purge_cdn_cache
Xóa ngay lập tức bộ nhớ đệm Cloudflare Edge CDN sau khi cập nhật các tệp hình ảnh.
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
urls | string[] | Không | Danh sách các URL hình ảnh hoặc đường dẫn tương đối CDN cần xóa. |
purge_all | boolean | Không | Có xóa toàn bộ bộ nhớ đệm của tên miền hay không (mặc định: false). |
🚀 Hướng dẫn cấu hình trên các công cụ AI
1. Claude for Desktop
Thêm cấu hình máy chủ vào tệp 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
{ "mcpServers": { "smallpict": { "command": "npx", "args": [ "-y", "@smallpict/mcp" ], "env": { "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY" } } }}Khởi động lại Claude Desktop, bạn sẽ thấy biểu tượng cây búa 🔨 kích hoạt các công cụ của SmallPict.
2. Cursor IDE
Cách A: Cài đặt toàn cục trong Cursor
- Mở Cursor Settings (
Cmd + ,hoặcCtrl + ,). - Vào Features → MCP Servers.
- Nhấp vào + Add New MCP Server:
- Name:
smallpict - Type:
command - Command:
npx -y @smallpict/mcp - Environment Variables:
SMALLPICT_API_KEY=sp_live_YOUR_API_KEY
- Name:
Cách B: Cấu hình theo từng dự án (.cursor/mcp.json)
Tạo một tệp tại .cursor/mcp.json trong thư mục gốc của dự án:
{ "mcpServers": { "smallpict": { "command": "npx", "args": [ "-y", "@smallpict/mcp" ], "env": { "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY" } } }}3. Google Antigravity (AGY)
Đối với các lập trình viên sử dụng môi trường Antigravity, thêm máy chủ vào ~/.gemini/antigravity/mcp/smallpict/mcp.json hoặc cấu hình không gian làm việc:
{ "mcpServers": { "smallpict": { "command": "npx", "args": [ "-y", "@smallpict/mcp" ], "env": { "SMALLPICT_API_KEY": "sp_live_YOUR_API_KEY" } } }}Giờ đây, các subagent Antigravity có thể tự động tối ưu hóa tài nguyên ảnh trong quá trình tái cấu trúc giao diện hoặc build ứng dụng.
4. VS Code (Cline / Roo Code)
- Mở bảng điều khiển Cline và nhấp vào biểu tượng MCP Servers.
- Chọn Configure MCP Servers (tệp
cline_mcp_settings.jsonsẽ mở ra). - Thêm cấu hình sau:
{ "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" ] } }}💬 Một số câu lệnh mẫu hữu ích khi trò chuyện với AI
Sau khi cài đặt xong, bạn có thể trò chuyện tự nhiên với AI mà không cần viết kịch bản lệnh:
Tối ưu hóa hàng loạt tệp ảnh cục bộ
"Trợ lý, hãy tìm tất cả các tệp ảnh PNG và JPEG trong thư mục
public/images/, chuyển đổi chúng sang WebP chất lượng 80 và lập bảng thống kê số byte đã tiết kiệm được."
Kiểm tra hạn ngạch tài khoản
"Kiểm tra xem tài khoản SmallPict của tôi còn bao nhiêu hạn ngạch trong tháng này trước khi tôi bắt đầu tối ưu hóa hàng loạt banner."
Xóa bộ nhớ đệm CDN
"Tôi vừa thay thế tệp
hero-banner.jpgtrên S3. Hãy xóa bộ nhớ đệm SmallPict CDN cho hình ảnh này giúp tôi."