@crabcrop/mcp 0.1.0 → 0.9.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -11,6 +11,14 @@
11
11
  * `buildSrcSet` does for widths: a value the server would 400
12
12
  * never gets signed.
13
13
  */
14
+ const PER_FORMAT_QUALITY_FORMATS = [
15
+ "avif",
16
+ "gif",
17
+ "jpeg",
18
+ "jxl",
19
+ "png",
20
+ "webp",
21
+ ];
14
22
  const MAX_DIMENSION = 16383;
15
23
  function fail(what, value, rule) {
16
24
  throw new Error(`${what} must be ${rule}, got ${JSON.stringify(value)}`);
@@ -89,10 +97,13 @@ function encodeArg(text) {
89
97
  }
90
98
  function className(what, name) {
91
99
  const trimmed = name.trim();
92
- if (trimmed.length < 1 ||
93
- trimmed.length > 64 ||
94
- !/^[\p{L}\p{N} _.\-/]+$/u.test(trimmed)) {
95
- fail(what, name, "1 to 64 characters of letters, digits, space, `_`, `.`, `-`, `/`");
100
+ // The server's bound is on UTF-8 bytes, not UTF-16 code
101
+ // units: a name of multibyte characters can pass a
102
+ // length check here and still be rejected there, so
103
+ // measure the encoded form, as the explainer does.
104
+ const bytes = new TextEncoder().encode(trimmed).length;
105
+ if (bytes < 1 || bytes > 64 || !/^[\p{L}\p{N} _.\-/]+$/u.test(trimmed)) {
106
+ fail(what, name, "1 to 64 UTF-8 bytes of letters, digits, space, `_`, `.`, `-`, `/`");
96
107
  }
97
108
  return encodeArg(name);
98
109
  }
@@ -110,6 +121,8 @@ const ANCHORS = [
110
121
  ];
111
122
  const BLEND_MODES = ["normal", "multiply", "screen", "overlay"];
112
123
  const CURVE_CHANNELS = ["rgb", "r", "g", "b"];
124
+ const STUDIO_MODES = ["product", "scene"];
125
+ const STUDIO_SHADOWS = ["soft", "strong", "none"];
113
126
  const IMAGE_FORMATS = ["jpeg", "jpg", "png", "webp", "jxl", "avif", "gif", "mp4", "webm"];
114
127
  /** Operation segments, one typed call per segment kind. */
115
128
  export const ops = {
@@ -142,6 +155,44 @@ export const ops = {
142
155
  const box = pixelBox("crop", width, height);
143
156
  return align === "center" ? `crop:${box}` : `crop:${box}:${align}`;
144
157
  },
158
+ /**
159
+ * `crop:300x200:objects(person,car):1.5`; crops to the
160
+ * union of every detection of the named classes, the
161
+ * union box scaled about its center by `scale` (1 is the
162
+ * tight box; the crop stays centered on the union).
163
+ * Needs a detection model configured on the server; when
164
+ * none of the classes is detected the render falls back
165
+ * to the plain center crop of the same size. Duplicate
166
+ * classes (case-insensitive) are spelled once, as the
167
+ * server's canonical form spells them; at most 32
168
+ * distinct classes, and a 33rd throws, since the server
169
+ * rejects it with `invalid_crop`.
170
+ */
171
+ cropObjects(width, height, classes, scale = 1) {
172
+ if (!Array.isArray(classes) || classes.length < 1) {
173
+ fail("crop objects classes", classes, "an array of 1 to 32 distinct class names");
174
+ }
175
+ // The cap counts distinct names, as the server's parser
176
+ // does (issue #408): repeats fold first and cost nothing.
177
+ const seen = new Set();
178
+ const names = [];
179
+ for (const name of classes) {
180
+ const encoded = className("crop objects class", name);
181
+ const key = typeof name === "string" ? name.trim().toLowerCase() : "";
182
+ if (!seen.has(key)) {
183
+ if (names.length === 32) {
184
+ fail("crop objects classes", classes, "an array of 1 to 32 distinct class names");
185
+ }
186
+ seen.add(key);
187
+ names.push(encoded);
188
+ }
189
+ }
190
+ if (!Number.isFinite(scale) || scale <= 0 || scale > 100) {
191
+ fail("crop objects scale", scale, "a number above 0 and at most 100");
192
+ }
193
+ const box = pixelBox("crop", width, height);
194
+ return `crop:${box}:objects(${names.join(",")}):${num(scale)}`;
195
+ },
145
196
  /** `crop-rect:10x20:110x220` (left x top : right x bottom). */
146
197
  cropRect(left, top, right, bottom) {
147
198
  intIn("crop-rect left", left, 0, 4294967295);
@@ -164,6 +215,19 @@ export const ops = {
164
215
  }
165
216
  return `focal:${left}x${top}:${right}x${bottom}`;
166
217
  },
218
+ /** `focalpoint:0.75x0.4:2` (fractions of the image dimensions, zoom optional); steers the next crop. */
219
+ focalPoint(x, y, zoom = 1) {
220
+ const frac = (what, v) => {
221
+ if (!Number.isFinite(v) || v < 0 || v > 1) {
222
+ fail(what, v, "a fraction from 0 to 1");
223
+ }
224
+ return v;
225
+ };
226
+ if (!Number.isFinite(zoom) || zoom <= 0 || zoom > 100) {
227
+ fail("focalpoint zoom", zoom, "a number above 0 and at most 100");
228
+ }
229
+ return `focalpoint:${num(frac("focalpoint x", x))}x${num(frac("focalpoint y", y))}:${num(zoom)}`;
230
+ },
167
231
  /** `pad:300x200`, optionally `:blur` or a RRGGBB fill color. */
168
232
  pad(width, height, fill) {
169
233
  const box = pixelBox("pad", width, height);
@@ -175,8 +239,12 @@ export const ops = {
175
239
  },
176
240
  /** `preset:thumb`; expands server-side. */
177
241
  preset(name) {
178
- if (name === "" || name.includes("/") || name.includes(":")) {
179
- fail("preset name", name, "a non-empty preset name without `/` or `:`");
242
+ // The server can only configure names from this
243
+ // charset (its preset file validation), so anything
244
+ // outside it is a reference that can only ever answer
245
+ // unknown_preset; refuse it here instead.
246
+ if (!/^[A-Za-z0-9_-]+$/.test(name)) {
247
+ fail("preset name", name, "letters, digits, `_`, `-` (the server's preset name charset)");
180
248
  }
181
249
  return `preset:${name}`;
182
250
  },
@@ -227,6 +295,9 @@ export const filter = {
227
295
  equalize() {
228
296
  return "equalize";
229
297
  },
298
+ enhance() {
299
+ return "enhance";
300
+ },
230
301
  removeBg() {
231
302
  return "removebg";
232
303
  },
@@ -242,9 +313,12 @@ export const filter = {
242
313
  pixelateFaces() {
243
314
  return "pixelatefaces";
244
315
  },
245
- /** Gaussian blur by sigma (positive). */
316
+ /** Gaussian blur by sigma: positive, at most the server's 512 cap. */
246
317
  blur(sigma) {
247
- return `blur(${num(positiveFloat("blur sigma", sigma))})`;
318
+ if (!Number.isFinite(sigma) || sigma <= 0 || sigma > 512) {
319
+ fail("blur sigma", sigma, "a positive number up to 512");
320
+ }
321
+ return `blur(${num(sigma)})`;
248
322
  },
249
323
  /** Unsharp-mask strength (positive). */
250
324
  sharpen(amount) {
@@ -258,6 +332,28 @@ export const filter = {
258
332
  contrast(percent) {
259
333
  return `contrast(${num(floatIn("contrast", percent, -100, 100))})`;
260
334
  },
335
+ /** Gamma correction divisor: 0 < g <= 10 (1 unchanged; above 1 brightens midtones). */
336
+ gamma(value) {
337
+ if (!Number.isFinite(value) || value <= 0 || value > 10) {
338
+ fail("gamma", value, "a number above 0 and at most 10");
339
+ }
340
+ return `gamma(${num(value)})`;
341
+ },
342
+ /** Exposure in stops: -10..10 (0 unchanged; +1 doubles the light, -1 halves it). */
343
+ exposure(stops) {
344
+ if (!Number.isFinite(stops) || stops < -10 || stops > 10) {
345
+ fail("exposure", stops, "a number between -10 and 10");
346
+ }
347
+ return `exposure(${num(stops)})`;
348
+ },
349
+ /** Highlights and shadows: two percents, each -100..100 (0 unchanged). */
350
+ highlightsShadows(highlights, shadows) {
351
+ return `highlights_shadows(${num(floatIn("highlights_shadows highlights", highlights, -100, 100))},${num(floatIn("highlights_shadows shadows", shadows, -100, 100))})`;
352
+ },
353
+ /** Vibrance percent: -100..100 (0 unchanged; muted colors move most, vivid colors are protected). */
354
+ vibrance(percent) {
355
+ return `vibrance(${num(floatIn("vibrance", percent, -100, 100))})`;
356
+ },
261
357
  /** Rotate the hue by integer degrees. */
262
358
  hueRotate(degrees) {
263
359
  return `huerotate(${intIn("huerotate degrees", degrees, -2147483648, 2147483647)})`;
@@ -352,17 +448,102 @@ export const filter = {
352
448
  trim(tolerance = 10) {
353
449
  return `trim(${intIn("trim tolerance", tolerance, 0, 255)})`;
354
450
  },
451
+ /** Trim uniform borders, then remove pixels per side (left, top, right, bottom). */
452
+ trimSides(tolerance, left, top, right, bottom) {
453
+ const side = (what, v) => intIn(what, v, 0, 4294967295);
454
+ return `trim(${intIn("trim tolerance", tolerance, 0, 255)},${side("trim left", left)},${side("trim top", top)},${side("trim right", right)},${side("trim bottom", bottom)})`;
455
+ },
355
456
  /** Encoding quality 1..100, or `"auto"` for perceptual targeting. */
356
457
  quality(value) {
357
458
  if (value === "auto")
358
459
  return "quality(auto)";
359
460
  return `quality(${intIn("quality", value, 1, 100)})`;
360
461
  },
361
- format(format) {
462
+ /**
463
+ * Per-format quality in one URL: a map of format to value
464
+ * (1..100 or "auto"), plus an optional fallback for
465
+ * formats with no entry. Resolved by the server after
466
+ * format negotiation; entries spell in canonical
467
+ * (format-name) order with the fallback first.
468
+ */
469
+ qualityPerFormat(entries, fallback) {
470
+ const names = Object.keys(entries);
471
+ if (names.length === 0 && fallback === undefined) {
472
+ fail("quality", "{}", "at least one entry or a fallback");
473
+ }
474
+ const parts = [];
475
+ if (fallback !== undefined) {
476
+ parts.push(fallback === "auto" ? "auto" : String(intIn("quality", fallback, 1, 100)));
477
+ }
478
+ for (const name of names.sort()) {
479
+ if (!PER_FORMAT_QUALITY_FORMATS.includes(name)) {
480
+ fail("quality", name, `one of ${PER_FORMAT_QUALITY_FORMATS.join(", ")}`);
481
+ }
482
+ const value = entries[name];
483
+ parts.push(`${name}:${value === "auto" ? "auto" : intIn("quality", value, 1, 100)}`);
484
+ }
485
+ return `quality(${parts.join(",")})`;
486
+ },
487
+ /** Indexed PNG output with at most this many colors, 2..256; other formats ignore it. */
488
+ palette(colors) {
489
+ return `palette(${intIn("palette colors", colors, 2, 256)})`;
490
+ },
491
+ /**
492
+ * Output format, with its encoder options (issue #319):
493
+ * `progressive` and `subsampling` (444, 422, or 420) for
494
+ * JPEG, `interlace` for PNG, `method` (0..6) and `sns`
495
+ * (smart subsampling, 0..100) for WebP. An option its
496
+ * format cannot honour throws here, like the server's 400.
497
+ */
498
+ format(format, options = {}) {
362
499
  if (!IMAGE_FORMATS.includes(format)) {
363
500
  fail("format", format, `one of ${IMAGE_FORMATS.join(", ")}`);
364
501
  }
365
- return `format(${format})`;
502
+ // The output segment is the canonical spelling: the
503
+ // `jpg` input alias spells as `jpeg`, like the server's
504
+ // canonical form.
505
+ const canonical = format === "jpg" ? "jpeg" : format;
506
+ const args = [canonical];
507
+ const used = (key) => options[key] !== undefined;
508
+ if (format === "jpeg" || format === "jpg") {
509
+ if (used("interlace") || used("method") || used("sns")) {
510
+ fail("format", JSON.stringify(options), "jpeg takes progressive and subsampling only");
511
+ }
512
+ if (options.progressive)
513
+ args.push("progressive");
514
+ if (options.subsampling !== undefined) {
515
+ if (![444, 422, 420].includes(options.subsampling)) {
516
+ fail("subsampling", options.subsampling, "one of 444, 422, 420");
517
+ }
518
+ args.push(`subsampling:${options.subsampling}`);
519
+ }
520
+ }
521
+ else if (format === "png") {
522
+ if (used("progressive") || used("subsampling") || used("method") || used("sns")) {
523
+ fail("format", JSON.stringify(options), "png takes interlace only");
524
+ }
525
+ if (options.interlace)
526
+ args.push("interlace");
527
+ }
528
+ else if (format === "webp") {
529
+ if (used("progressive") || used("subsampling") || used("interlace")) {
530
+ fail("format", JSON.stringify(options), "webp takes method and sns only");
531
+ }
532
+ if (options.method !== undefined) {
533
+ args.push(`method:${intIn("method", options.method, 0, 6)}`);
534
+ }
535
+ if (options.sns !== undefined) {
536
+ args.push(`sns:${intIn("sns", options.sns, 0, 100)}`);
537
+ }
538
+ }
539
+ else if (used("progressive") ||
540
+ used("subsampling") ||
541
+ used("interlace") ||
542
+ used("method") ||
543
+ used("sns")) {
544
+ fail("format", JSON.stringify(options), `${format} takes no encoder options`);
545
+ }
546
+ return `format(${args.join(",")})`;
366
547
  },
367
548
  /** The background color other operations pad with (RRGGBB). */
368
549
  fill(color) {
@@ -372,6 +553,48 @@ export const filter = {
372
553
  facePad(amount) {
373
554
  return `facepad(${num(floatIn("facepad", amount, 0, 3))})`;
374
555
  },
556
+ /**
557
+ * Studio mode: `studio(product)` composites the subject
558
+ * the server's segmentation model finds onto a backdrop
559
+ * with a synthesized contact shadow, scaled and centered
560
+ * to the pad margin; `studio(scene)` keeps the
561
+ * photograph's scene, reframing it on the detected
562
+ * subject and correcting light and color. See
563
+ * {@link StudioOptions} for the named arguments.
564
+ * Arguments spelled at their defaults (shadow `soft`,
565
+ * pad 10) are omitted, matching the server's canonical
566
+ * spelling, so `studio("product", { pad: 10 })` and
567
+ * `studio("product")` are the same string.
568
+ */
569
+ studio(mode, options = {}) {
570
+ if (!STUDIO_MODES.includes(mode)) {
571
+ fail("studio mode", mode, `one of ${STUDIO_MODES.join(", ")}`);
572
+ }
573
+ const { bg, shadow, pad } = options;
574
+ if (mode === "scene" && (bg !== undefined || shadow !== undefined)) {
575
+ fail("studio scene options", options, "pad only: bg and shadow are product arguments");
576
+ }
577
+ const parts = [mode];
578
+ if (mode === "product") {
579
+ if (bg !== undefined) {
580
+ const value = bg === "white" || bg === "brand" || bg === "none" ? bg : hex6("studio bg", bg);
581
+ parts.push(`bg:${value}`);
582
+ }
583
+ if (shadow !== undefined) {
584
+ if (!STUDIO_SHADOWS.includes(shadow)) {
585
+ fail("studio shadow", shadow, `one of ${STUDIO_SHADOWS.join(", ")}`);
586
+ }
587
+ if (shadow !== "soft")
588
+ parts.push(`shadow:${shadow}`);
589
+ }
590
+ }
591
+ if (pad !== undefined) {
592
+ intIn("studio pad", pad, 0, 40);
593
+ if (pad !== 10)
594
+ parts.push(`pad:${pad}`);
595
+ }
596
+ return `studio(${parts.join(",")})`;
597
+ },
375
598
  /** AI upscale by the given factor. */
376
599
  upscale(factor) {
377
600
  if (factor !== 2 && factor !== 4) {
@@ -400,9 +623,9 @@ export const filter = {
400
623
  intIn("radius", c, 0, MAX_DIMENSION);
401
624
  return `radius(${corners.join(",")})`;
402
625
  },
403
- /** Paint an opaque border inside the frame (RRGGBB). */
626
+ /** Paint an opaque border inside the frame (RRGGBB); a width of 0 is a no-op. */
404
627
  border(width, color) {
405
- return `border(${intIn("border width", width, 1, MAX_DIMENSION)},${hex6("border color", color)})`;
628
+ return `border(${intIn("border width", width, 0, MAX_DIMENSION)},${hex6("border color", color)})`;
406
629
  },
407
630
  mask(shape) {
408
631
  if (shape !== "circle" && shape !== "ellipse") {
@@ -473,6 +696,10 @@ export const filter = {
473
696
  pixelateClass(name) {
474
697
  return `pixelateclass(${className("pixelateclass name", name)})`;
475
698
  },
699
+ /** Recolor every detected object of the named class to the given RRGGBB color. */
700
+ recolorClass(name, color) {
701
+ return `recolorclass(${className("recolorclass name", name)},${hex6("recolorclass color", color)})`;
702
+ },
476
703
  /** Blur the rectangle (x, y, w, h) in pixels. */
477
704
  blurRegion(x, y, w, h) {
478
705
  return `blur_region(${region(x, y, w, h)})`;
@@ -481,6 +708,10 @@ export const filter = {
481
708
  pixelateRegion(x, y, w, h) {
482
709
  return `pixelate_region(${region(x, y, w, h)})`;
483
710
  },
711
+ /** Erase the rectangle (x, y, w, h) in pixels and inpaint it (AI). */
712
+ removeRegion(x, y, w, h) {
713
+ return `remove_region(${region(x, y, w, h)})`;
714
+ },
484
715
  };
485
716
  function region(x, y, w, h) {
486
717
  intIn("region x", x, 0, MAX_DIMENSION);
@@ -21,10 +21,10 @@
21
21
  "test": "node --test"
22
22
  },
23
23
  "type": "module",
24
- "version": "0.1.0",
24
+ "version": "0.9.11",
25
25
  "devDependencies": {
26
26
  "@types/node": "^26.6.5",
27
- "typescript": "^5.9.3"
27
+ "typescript": "^7.0.2"
28
28
  },
29
29
  "main": "./dist/index.js",
30
30
  "types": "./dist/index.d.ts"
package/package.json CHANGED
@@ -15,7 +15,7 @@
15
15
  "test": "node --test test/*.test.mjs"
16
16
  },
17
17
  "type": "module",
18
- "version": "0.1.0",
18
+ "version": "0.9.11",
19
19
  "devDependencies": {
20
20
  "@types/node": "^26.6.5",
21
21
  "typescript": "^5.9.3"
package/server.json CHANGED
@@ -1 +1 @@
1
- {"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","description":"Sign and explain crabcrop image URLs, fetch processed-image metadata, and purge cached results.","name":"io.github.crabcrop/crabcrop","packages":[{"environmentVariables":[{"description":"Base URL of the crabcrop server the tools act on (for example https://images.example.com).","format":"string","isRequired":false,"isSecret":false,"name":"CRABCROP_BASE"},{"description":"The server's signing secret, used by sign_url and purge_result. Keep it in the environment, not in tool arguments.","format":"string","isRequired":false,"isSecret":true,"name":"CRABCROP_SECRET"}],"identifier":"@crabcrop/mcp","registryBaseUrl":"https://registry.npmjs.org","registryType":"npm","runTimeHint":"npx","transport":{"type":"stdio"},"version":"0.1.0"}],"repository":{"source":"github","url":"https://github.com/dayvson/crabcrop"},"version":"0.1.0"}
1
+ {"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","description":"Sign and explain crabcrop image URLs, fetch processed-image metadata, and purge cached results.","name":"io.github.crabcrop/crabcrop","packages":[{"environmentVariables":[{"description":"Base URL of the crabcrop server the tools act on (for example https://images.example.com).","format":"string","isRequired":false,"isSecret":false,"name":"CRABCROP_BASE"},{"description":"The server's signing secret, used by sign_url and purge_result. Keep it in the environment, not in tool arguments.","format":"string","isRequired":false,"isSecret":true,"name":"CRABCROP_SECRET"}],"identifier":"@crabcrop/mcp","registryBaseUrl":"https://registry.npmjs.org","registryType":"npm","runTimeHint":"npx","transport":{"type":"stdio"},"version":"0.9.11"}],"repository":{"source":"github","url":"https://github.com/dayvson/crabcrop"},"version":"0.9.11"}