sprig-fit-mcp

Sprig Fit MCP

Local image inspection and preparation for AI agents. The MCP host launches this Node.js process using stdio. Images are processed on that machine with Sharp. No processing API, object storage, account, telemetry or remote image upload is used. npm may access its registry to install the package.

Distributed as sprig-fit-mcp under the MIT license. MCP Registry name: io.github.BillyQin/sprig-fit (case-sensitive, matching the authenticated GitHub namespace).

Requirements

• Node.js 22 or newer, npm, and a host that can launch local stdio MCP processes.
• A supported Sharp platform. Native dependencies are installed by npm; this is not a browser package.
• Static JPEG, PNG and WebP. HEIC, animated images, SVG and PDF are rejected in v0.1.
• Local files visible to the MCP process. A cloud agent's container filesystem is different from an end user's laptop; mount the required input/output directories when using containers.

Run from this repository

npm ci --prefix packages/mcp
npm --prefix packages/mcp run build
node packages/mcp/dist/cli.js --output-dir /absolute/path/to/results

The last command waits for MCP JSON-RPC messages on stdin. It is not an interactive image command. Use a compatible MCP client to call its tools. --help and --version are available.

Host configuration (npm)

For the published npm release, configure a compatible MCP host as follows:

{
  "mcpServers": {
    "sprig-fit": {
      "command": "npx",
      "args": ["-y", "sprig-fit-mcp@0.1.1", "--output-dir", "/absolute/path/to/results"]
    }
  }
}

Configuration format varies by host. For a built local checkout, set command to node and args to the absolute packages/mcp/dist/cli.js path followed by --output-dir and its value. Prefer a pinned release version for reproducibility.

Tools

Exactly two tools are exposed. Each declares a JSON input/output schema. Successful results include structured JSON and a JSON text fallback. Tool execution failures use isError: true plus JSON text containing status, code, message, and details; they do not pretend that a file was created.

inspect_image

{
  "source": { "path": "/absolute/path/to/photo.jpg" },
  "include_preview": true
}

Returns status: "success" and image with width, height, bytes, format, mime_type, has_transparency, and orientation_corrected. Dimensions reflect EXIF orientation. Raw EXIF, GPS and source metadata are not returned. Optional preview is a JPEG no larger than 512×512, composited on white; it is not the output file or the original.

prepare_image

{
  "source": { "path": "/absolute/path/to/photo.jpg" },
  "format": "jpeg",
  "size": { "width": 1080, "height": 1350, "unit": "px" },
  "fit": "cover",
  "anchor": "center",
  "max_bytes": 500000,
  "allow_upscale": false,
  "conflict_policy": "error"
}

Field	Behavior
source.path	Required local path. Relative paths use the MCP process working directory. URLs, browser blob URLs, upload IDs and client attachment IDs are not accepted in this local release.
format	Required jpeg, png, or webp.
size	Optional. Width and/or height; unit px (default) or in; PPI 1–1200 (default 300). One dimension derives the other from the extracted image's ratio. Omit to keep full original/cropped pixels, not the website's half-size Original default.
crop	Optional {x,y,width,height} percentages, 0–100, within the EXIF-oriented original. Extraction happens first, then fitting; cover can crop that extracted region further.
fit	contain (default): preserve the frame with letterboxing as needed; cover: crop to fill exact dimensions. No stretching mode.
anchor	center (default), top, right, bottom, or left, used for fitting. Centering does not detect people or subjects.
background	Optional #RRGGBB. Required for JPEG transparency or letterboxing. PNG/WebP preserve transparency when omitted.
max_bytes	Optional positive integer, up to 100,000,000. Includes output metadata. 1 KB=1,000 bytes.
allow_upscale	Default false. A requested fit that needs enlargement returns UPSCALE_REQUIRED.
conflict_policy	Default error: do not reduce requested dimensions. shrink: allow proportional downscaling when the byte limit cannot otherwise be met.

JPEG/WebP quality is searched from 95 down to a floor of 50. PNG is lossless and does not fake quality reduction. With shrink, dimensions are searched at quality 85 then improved within the byte cap. This is a practical bounded search, not proof of a globally optimal encoding.

JPEG/PNG inch output receives print density metadata. WebP receives the corresponding pixel dimensions plus a warning about absent print PPI metadata. Source EXIF is removed from generated images. Different encoders may produce different bytes from the browser version; actual constraints are checked.

Successful structured output example (illustrative values):

{
  "status": "success",
  "output": {
    "path": "/absolute/path/to/results/generated.jpg",
    "uri": "file:///absolute/path/to/results/generated.jpg",
    "mime_type": "image/jpeg",
    "width": 1080,
    "height": 1350,
    "bytes": 438215,
    "format": "jpeg"
  },
  "checks": { "dimensions_met": true, "max_bytes_met": true },
  "dimensions_adjusted": false,
  "warnings": []
}

When shrinking is authorized and necessary, dimensions_met is false, max_bytes_met is true, and the actual reduced dimensions are returned. Without a byte cap, max_bytes_met is null.

How files are returned

• Files are saved under the trusted host's --output-dir, default ./sprig-output. Tool arguments cannot select an arbitrary output path. Each result gets a random new filename; source and existing result files are not overwritten.
• output.path and output.uri point to the actual local file, with no download server or expiry. The files persist after the MCP process exits; the caller manages retention/deletion.
• A resource_link with a sprig-image://outputs/... URI is also returned. A host supporting resources/read can retrieve the exact bytes through MCP, even if it does not directly open local paths. Only generated files are exposed, never arbitrary input paths. Resource references remain readable during this server session for the most recent 256 results; local files are not deleted when references expire.
• Displaying/saving the result for an end user depends on the host. A local file path does not create a publicly accessible download link.

Limits and errors

Input: up to 30 MB, 24 MP, 16384 px per side. Output: up to 16 MP, 8192 px per side. Native image operations have time limits and preparation has a 60-second budget; image tasks are serialized to bound memory. Cancellation is checked between processing stages and before saving; it is not an instant native-code interrupt.

Examples of error codes: SOURCE_UNREADABLE, UNSUPPORTED_FORMAT, ANIMATION_UNSUPPORTED, INVALID_ARGUMENT, BACKGROUND_REQUIRED, UPSCALE_REQUIRED, CONSTRAINTS_UNSATISFIABLE, FILE_LIMIT_TOO_SMALL, OUTPUT_UNWRITABLE, CANCELLED. A conflict includes actionable suggestions to increase the limit, allow shrinking, or change format. No image or raw exception is sent to an analytics service.

Reuse as a library

import { readFile } from "node:fs/promises";
import { inspectImage, prepareImage } from "sprig-fit-mcp";

const input = await readFile("photo.jpg");
const info = await inspectImage(input);
const result = await prepareImage(input, { format: "webp", max_bytes: 500000 });
// result.data is a Buffer; library callers choose where to save it.

Validation and publication

npm --prefix packages/mcp test
cd packages/mcp
npm pack

Tests independently decode outputs, verify crop orientation and print metadata, exercise true stdio MCP calls and resources/read, and ensure errors do not create files or overwrite originals. The SDK is pinned to 1.32.1; its supported protocol negotiation includes 2025-11-25. This release does not claim to implement every feature of the separate 2026-07-28 protocol revision.

The official Registry stores metadata, not runnable code or image files. This is an npm/stdio package entry, with no remotes URL. Publish from this package directory (not the website root): sign in to npm, run npm publish --dry-run --access public, then npm publish --access public. Publishing runs the package tests and build. After verifying npm version 0.1.1 and its mcpName, authenticate with mcp-publisher login github using BillyQin, then run mcp-publisher validate server.json and mcp-publisher publish server.json. Keep package and manifest versions/names synchronized, including exact namespace capitalization. No mcp-publisher init is needed because the manifest already exists. Version 0.1.1 corrects the Registry identity in 0.1.0; published npm versions cannot be overwritten.

Official guidance: Registry quickstart, package types, remote vs package entries.