@spronta/mcp 0.1.1 → 0.1.2

package/README.md

@@ -1,30 +1,41 @@
 # @spronta/mcp
 
-MCP server for the [Spronta](https://www.spronta.com) Image CDN. Lets LLMs manage image projects, upload images, create presets, generate signed URLs, and more.
+MCP server for uploading, transforming, and serving images on a global CDN — directly from AI assistants.
 
-## Install
+Connect Claude, GPT, Cursor, Windsurf, or any [MCP](https://modelcontextprotocol.io)-compatible client to the [Spronta](https://www.spronta.com) Image CDN. Upload images from URLs or base64, apply real-time transforms (resize, crop, format conversion, smart crop, blurhash), create reusable presets, generate signed URLs, and monitor usage — all through natural language.
 
-```bash
-npm install -g @spronta/mcp
-```
+## Why use this?
+
+- **Upload images from AI** — give your LLM an image URL and it uploads, optimizes, and returns a CDN link
+- **Real-time transforms** — resize, crop, convert to WebP/AVIF/JXL, smart crop with face detection
+- **Global CDN delivery** — images served from edge locations worldwide
+- **Blurhash generation** — automatic blur placeholders computed on upload
+- **Signed URLs** — HMAC-SHA256 signed URLs with expiration for private images
+- **Named presets** — create reusable transform configurations (e.g. `thumbnail`, `hero`, `og-image`)
+- **No vendor lock-in** — MIT licensed, open source
 
-Or use directly with `npx`:
+## Quick start
+
+### Install
 
 ```bash
+npm install -g @spronta/mcp
+# or use directly
 npx @spronta/mcp
 ```
 
-## Setup
-
 ### Claude Code
 
 ```bash
-claude mcp add spronta -e SPRONTA_API_KEY=spronta_img_... -e SPRONTA_PROJECT_ID=your-project-id -- npx @spronta/mcp
+claude mcp add spronta \
+  -e SPRONTA_API_KEY=spronta_img_... \
+  -e SPRONTA_PROJECT_ID=your-project-id \
+  -- npx @spronta/mcp
 ```
 
-### Claude Desktop / Cursor
+### Claude Desktop / Cursor / Windsurf
 
-Add to your MCP config:
+Add to your MCP configuration file:
 
 ```json
 {
@@ -41,58 +52,128 @@ Add to your MCP config:
 }
 ```
 
+### Get your API key
+
+1. Sign up at [app.spronta.com](https://app.spronta.com/sign-up) (free tier: 100 images)
+2. Create a project in the dashboard
+3. Copy your API key from project settings
+
 ## Environment variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `SPRONTA_API_KEY` | Yes | Your project API key (from the Spronta dashboard) |
-| `SPRONTA_PROJECT_ID` | No | Default project ID — can also be passed per-tool |
+| `SPRONTA_API_KEY` | Yes | Your project API key |
+| `SPRONTA_PROJECT_ID` | No | Default project ID (can also be passed per-tool) |
 | `SPRONTA_API_URL` | No | API base URL (default: `https://app.spronta.com/api`) |
 
-## Available tools
+## 18 tools available
 
 ### Projects
-- `list_projects` — List all image projects
-- `create_project` — Create a new project
-- `get_project` — Get project details with usage stats
-- `update_project` — Update name or custom domain
-- `delete_project` — Permanently delete a project
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all image projects |
+| `create_project` | Create a new project |
+| `get_project` | Get project details with usage stats |
+| `update_project` | Update name or custom domain |
+| `delete_project` | Permanently delete a project |
+
+### Upload & Images
+| Tool | Description |
+|------|-------------|
+| `upload_image` | Upload from URL or base64 — handles presigned upload, blurhash generation, and CDN URL creation in one call |
+| `list_images` | List images with pagination |
+| `update_image` | Update alt text and tags |
+| `delete_image` | Delete an image from CDN and storage |
+
+### Transform Presets
+| Tool | Description |
+|------|-------------|
+| `list_presets` | List named transform presets |
+| `create_preset` | Create a preset (use in CDN URLs with `?t=name`) |
+| `update_preset` | Update a preset's name or transforms |
+| `delete_preset` | Delete a preset |
+
+### URL Signing
+| Tool | Description |
+|------|-------------|
+| `get_signing_config` | Get URL signing configuration |
+| `update_signing` | Enable/disable HMAC-SHA256 signing |
+| `generate_signed_url` | Generate a signed CDN URL with optional expiration |
+
+### Analytics & Utility
+| Tool | Description |
+|------|-------------|
+| `get_usage` | Get daily metrics (requests, bandwidth, transforms) |
+| `build_cdn_url` | Build a CDN URL with transform parameters (no API call) |
 
-### Upload
-- `upload_image` — Upload an image from URL or base64. Handles the full upload flow (presigned URL → upload → confirm) and returns the CDN URL with blurhash.
+## Example prompts
 
-### Images
-- `list_images` — List images with pagination
-- `update_image` — Update alt text and tags
-- `delete_image` — Delete an image
+Once connected, just ask your AI:
 
-### Presets
-- `list_presets` — List named transform presets
-- `create_preset` — Create a preset (use in URLs with `?t=name`)
-- `update_preset` — Update a preset
-- `delete_preset` — Delete a preset
+```
+> Upload this image to my project: https://example.com/photo.jpg
 
-### Signing
-- `get_signing_config` — Get URL signing configuration
-- `update_signing` — Enable/disable signing
-- `generate_signed_url` — Generate an HMAC-SHA256 signed URL
+> Create a thumbnail preset: 200x200, cover crop, face detection, webp format
 
-### Usage
-- `get_usage` — Get daily metrics (requests, bandwidth, transforms)
+> How many requests did my project handle this week?
 
-### Utility
-- `build_cdn_url` — Build a CDN URL with transform parameters (no API call)
+> Generate a signed URL for hero.jpg that expires in 1 hour
 
-## Example prompts
+> List all my images and update the alt text on the product shots
 
-Once connected, you can ask your LLM:
+> Build a CDN URL for banner.png at 1200px wide in avif format
+```
 
-- "List my Spronta projects"
-- "Upload this image to my project: https://example.com/photo.jpg"
-- "Create a thumbnail preset: 200x200, cover, face gravity, webp"
-- "How many requests did my project get this week?"
-- "Generate a signed URL for hero.jpg that expires in 1 hour"
-- "Build a CDN URL for photo.jpg at 800px wide in webp format"
+## Transform options
+
+When creating presets or building URLs, these transforms are available:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `width` | integer | Output width (1–8192) |
+| `height` | integer | Output height (1–8192) |
+| `fit` | string | `cover`, `contain`, `fill`, `scale-down`, `crop`, `pad` |
+| `format` | string | `auto`, `webp`, `avif`, `jpeg`, `png`, `jxl` |
+| `quality` | integer | 1–100 |
+| `qualityMode` | string | `high`, `medium`, `low` (perceptual targeting) |
+| `gravity` | string | `auto`, `face`, `center`, position keywords |
+| `blur` | integer | Gaussian blur (1–250) |
+| `sharpen` | number | Unsharp mask (0–10) |
+| `radius` | integer | Corner radius (1–9999, or "max" for circle) |
+| `grayscale` | boolean | Convert to grayscale |
+| `brightness` | integer | -100 to 100 |
+| `contrast` | number | -100 to 100 |
+| `saturation` | integer | -100 to 100 |
+| `sepia` | boolean | Sepia tone filter |
+| `rotate` | integer | 90, 180, 270 |
+| `flip` | string | `h` (horizontal), `v` (vertical) |
+
+## How upload works
+
+The `upload_image` tool handles the full upload pipeline in a single call:
+
+1. You provide an image URL (or base64 data) and a filename
+2. The server fetches the image
+3. Requests a presigned upload URL from Spronta
+4. Uploads the file directly to storage
+5. Confirms the upload — Spronta computes the blurhash and detects dimensions
+6. Returns the confirmed image with CDN URL, blurhash, and metadata
+
+## Related packages
+
+- [`@spronta/images`](https://www.npmjs.com/package/@spronta/images) — Core URL builder SDK (zero deps)
+- [`@spronta/images-react`](https://www.npmjs.com/package/@spronta/images-react) — React components
+- [`@spronta/images-next`](https://www.npmjs.com/package/@spronta/images-next) — Next.js integration
+- [WordPress plugin](https://github.com/spronta/wordpress-plugin) — Automatic CDN for WordPress
+
+## Links
+
+- [Website](https://www.spronta.com)
+- [Documentation](https://www.spronta.com/docs)
+- [API Reference](https://www.spronta.com/docs/api)
+- [OpenAPI Spec](https://www.spronta.com/openapi.yaml)
+- [GitHub](https://github.com/spronta/mcp)
+- [npm](https://www.npmjs.com/package/@spronta/mcp)
 
 ## License
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@spronta/mcp",
-  "version": "0.1.1",
-  "description": "Spronta Image CDN — MCP server for LLM integrations",
+  "version": "0.1.2",
+  "description": "Spronta Image CDN — MCP server for LLM integrations. Upload, transform, and deliver images via AI agents.",
+  "mcpName": "io.github.spronta/images",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",