@layerporter/image-optimizer-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,124 +1,116 @@
 # LayerPorter Website Image Optimizer MCP
 
-Technical candidate for page-aware website image optimization through Model Context Protocol.
+Public MCP server for website image analysis and safe image optimization.
 
-## Status
+## Install
 
-The package is release-prepared but is **not yet claimed as a public npm or Official MCP Registry release**. Publication status changes only after the exact npm version and Registry entry are externally verified.
-
-Registry identity:
+```bash
+npx -y @layerporter/image-optimizer-mcp@latest
+```
 
 - npm package: `@layerporter/image-optimizer-mcp`
 - MCP server: `com.layerporter/website-image-optimizer`
 - transport: `stdio`
 - Node.js: `>=22.12.0`
+- repository: `https://github.com/OlegStrateg/lp-site`
+- product page: `https://layerporter.com/mcp/website-image-optimizer/`
 
-The npm package carries `mcpName: com.layerporter/website-image-optimizer`, matching `server.json`, so the Official MCP Registry can verify package ownership after the package exists publicly on npm.
+The npm package is publicly available. Official MCP Registry publication is a separate distribution step and is not implied by npm publication.
 
-## Tools
+## What it does
 
-The current server registers seven bounded tools:
+The server registers seven bounded tools:
 
-- `analyze_page_images`
-- `optimize_image`
-- `generate_responsive_variants`
-- `compare_image_versions`
-- `optimize_page_images`
-- `analyze_url_images`
-- `optimize_url_images`
+- `analyze_page_images` — analyze caller-provided page/image facts;
+- `optimize_image` — optimize one image;
+- `generate_responsive_variants` — generate resized image variants without upscaling;
+- `compare_image_versions` — compare image versions;
+- `optimize_page_images` — optimize a bounded set of page images;
+- `analyze_url_images` — inspect images referenced by static HTML at a public URL;
+- `optimize_url_images` — fetch and optimize a bounded set of raster images referenced by static HTML.
 
-The first five operate on caller-provided image data or normalized page facts. The two URL tools perform bounded read-only HTTP(S) fetching through a dedicated SSRF-protected network boundary. URL mode is intentionally a fast static-HTML mode: it does not claim browser-rendered size, `currentSrc`, LCP, CSS-background discovery, or JavaScript-driven lazy content.
+Accepted optimized binaries are returned through temporary MCP `resource_link` values and read separately with `resources/read`.
 
-Accepted optimized binaries are exposed as temporary MCP `resource_link` values and are read separately with `resources/read`; they are not embedded in the initial tool text response.
+## Input and output boundary
 
-## Runtime
+Untrusted image input is fail-closed:
 
-- Node.js `>=22.12.0`
-- MCP v2 server package
-- stdio transport
-- image processing through the shared image core / Sharp / libvips
+- accepted input decoders: JPEG, PNG, WebP;
+- blocked input decoders: HEIF/AVIF, TIFF, GIF, SVG, and unknown formats;
+- AVIF remains available as an output format.
 
-## Local source setup
+The optimizer applies bounded transformations and does not upscale images.
 
-A source checkout does not contain the generated `src/image-core` copy. Sync it explicitly before MCP tests or direct server startup:
+## URL mode limitations
 
-```bash
-cd packages/image-core
-npm install --no-audit --no-fund
-npm test
-
-cd ../image-optimizer-mcp
-npm install --ignore-scripts --no-audit --no-fund
-npm run release:preflight
-npm run sync:core
-npm test
-node src/server.js
-```
+URL mode is intentionally a fast static-HTML path. It does **not** claim to provide a browser-rendered audit.
 
-The last command starts the stdio MCP server and waits for a client connection. `npm pack` also runs `sync:core` through `prepack`; source setup and packed-artifact setup are verified separately.
+It does not discover or measure:
 
-## Installation after public release
+- browser-selected `currentSrc`;
+- real LCP;
+- CSS background images;
+- JavaScript-injected or lazy-loaded content that is absent from the fetched HTML;
+- production page write/apply behavior.
 
-Do not treat this command as available until the npm package has actually been published and verified:
+Use it for bounded static discovery and optimization, not as a replacement for a browser runtime or Core Web Vitals measurement.
 
-```bash
-npx -y @layerporter/image-optimizer-mcp
-```
-
-## License
+## Safety
 
-This package is proprietary LayerPorter software. The official unmodified package may be downloaded, installed, and used under the terms in `LICENSE`. Copying beyond technically necessary installation/runtime copies, modification, derivative works, repackaging, redistribution, sublicensing, resale, and unauthorized hosting are prohibited.
+The package:
 
-The software is licensed, not sold. Third-party dependencies remain governed by their own licenses.
-
-## Release model
-
-The first npm version is a bootstrap release: npm staged publishing and Trusted Publisher configuration require the package to already exist. The first public package therefore must be published by the package owner with npm account 2FA. After that bootstrap, GitHub Actions Trusted Publishing can be configured for `.github/workflows/image-mcp-release.yml`, and later versions can use the staged OIDC release path.
-
-Official MCP Registry publication happens only **after** the matching npm version is publicly available. The Registry namespace uses ownership of `layerporter.com` and the server name `com.layerporter/website-image-optimizer`.
+- performs public HTTP(S) reads only through the two URL tools;
+- blocks unsafe URL schemes, credentials, localhost/private/link-local/reserved destinations, unsafe DNS answers, and redirects to prohibited addresses;
+- caps page bytes, image bytes, total accepted bytes, redirects, image count, timeouts, and concurrency;
+- writes accepted output only to an isolated temporary artifact store;
+- does not execute shell commands;
+- does not perform arbitrary filesystem writes;
+- does not modify a website or production environment.
 
-## Safety boundary
+Temporary artifacts are process-local and ephemeral. The default TTL is 30 minutes; cleanup is performed during store operations/disposal rather than at an exact wall-clock instant.
 
-The current MCP package:
+## Quick usage examples
 
-- performs bounded public HTTP(S) reads only through `analyze_url_images` and `optimize_url_images`;
-- blocks unsafe URL schemes, URL credentials, localhost/private/link-local/reserved targets, unsafe DNS answers and redirects to prohibited addresses;
-- caps page bytes, per-image bytes, accepted total image bytes, redirects, image count, timeouts and concurrency;
-- writes accepted image artifacts only to its isolated temporary artifact store;
-- does not perform arbitrary filesystem write/delete/rename operations;
-- does not execute shell commands;
-- does not write to a website or production environment.
+After connecting the MCP server to a compatible client, requests can be framed around the task:
 
-Local transform tools consume caller-provided image buffers or normalized page facts. URL tools are read-only open-world operations. Hard safety comes from implementation controls, not only from MCP metadata.
+- “Analyze the images referenced by this page URL.”
+- “Optimize this JPEG for web delivery without upscaling.”
+- “Generate responsive variants for this image.”
+- “Compare these two image versions and report the byte difference.”
 
-Temporary artifacts are process-local and ephemeral. Their default TTL is 30 minutes, but cleanup occurs during store operations/disposal rather than as a guarantee of physical deletion at an exact wall-clock instant. `resources/read` returns the resource blob separately; whether a client places that blob into model context is client-specific.
+Client-specific MCP configuration differs by product, so use the MCP client’s current documentation for its exact server configuration format.
 
 ## Verification
 
-Release preparation verifies:
+The release process verifies:
 
-- package/server identity consistency;
-- proprietary license metadata and packaged `LICENSE` presence;
+- package/server identity and version consistency;
 - image-core and MCP tests;
 - packed npm artifact metadata;
 - clean installation of the packed tarball;
-- real stdio startup and client handshake from the packed artifact;
-- `tools/list`, transform calls, temporary `resource_link` and `resources/read`;
-- Official MCP Registry `server.json` validation;
-- full LayerPorter Astro build in the integrated repository tree.
+- stdio startup and MCP client handshake;
+- exactly seven expected tools;
+- real tool calls;
+- temporary `resource_link` and `resources/read`;
+- public-package source equivalence after publication.
+
+## License
+
+This package is proprietary LayerPorter software. The official unmodified package may be downloaded, installed, and used under the terms in `LICENSE`.
 
-## Public documentation
+Copying beyond technically necessary installation/runtime copies, modification, derivative works, repackaging, redistribution, sublicensing, resale, and unauthorized hosting are prohibited. Third-party dependencies remain governed by their own licenses.
 
-Canonical product pages after site release:
+## Links
 
-- `https://layerporter.com/mcp/website-image-optimizer/`
-- `https://layerporter.com/docs/mcp/website-image-optimizer/`
+- Product: `https://layerporter.com/mcp/website-image-optimizer/`
+- Documentation: `https://layerporter.com/docs/mcp/website-image-optimizer/`
+- Repository: `https://github.com/OlegStrateg/lp-site`
+- Issues: `https://github.com/OlegStrateg/lp-site/issues`
 
-## Not yet included
+## Not included
 
-- confirmed public npm release;
-- confirmed Official MCP Registry publication;
-- hosted endpoint;
+- Official MCP Registry publication;
+- hosted remote endpoint;
 - full browser crawler/runtime metrics collection;
-- production apply/write tool;
-- universal performance or quality claims.
+- production apply/write tools;
+- universal performance, quality, or Core Web Vitals guarantees.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@layerporter/image-optimizer-mcp",
-  "version": "0.1.0",
-  "description": "Page-aware MCP server for deterministic website image analysis and safe optimization.",
+  "version": "0.1.2",
+  "description": "MCP server for website image analysis, safe compression, resizing, responsive variants, and WebP/AVIF output.",
   "mcpName": "com.layerporter/website-image-optimizer",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -30,12 +30,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/OlegStrateg/layerporter-site.git",
+    "url": "git+https://github.com/OlegStrateg/lp-site.git",
     "directory": "packages/image-optimizer-mcp"
   },
   "homepage": "https://layerporter.com/mcp/website-image-optimizer/",
   "bugs": {
-    "url": "https://github.com/OlegStrateg/layerporter-site/issues"
+    "url": "https://github.com/OlegStrateg/lp-site/issues"
   },
   "keywords": [
     "mcp",

package/server.json

@@ -2,19 +2,19 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "com.layerporter/website-image-optimizer",
   "title": "LayerPorter Website Image Optimizer",
-  "description": "Page-aware website image analysis and safe optimization MCP server.",
+  "description": "Website image analysis and safe optimization for compression, resizing, and responsive variants.",
   "websiteUrl": "https://layerporter.com/mcp/website-image-optimizer/",
   "repository": {
-    "url": "https://github.com/OlegStrateg/layerporter-site",
+    "url": "https://github.com/OlegStrateg/lp-site",
     "source": "github",
     "subfolder": "packages/image-optimizer-mcp"
   },
-  "version": "0.1.0",
+  "version": "0.1.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@layerporter/image-optimizer-mcp",
-      "version": "0.1.0",
+      "version": "0.1.2",
       "transport": {
         "type": "stdio"
       }

package/src/image-core/index.js

@@ -1,12 +1,48 @@
 import sharp from 'sharp';
 import { chooseOutputFormat, validatePolicy } from './policy.js';
 
+const ALLOWED_UNTRUSTED_BUFFER_LOADERS = Object.freeze([
+  'VipsForeignLoadJpegBuffer',
+  'VipsForeignLoadPngBuffer',
+  'VipsForeignLoadWebpBuffer',
+]);
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+// Native decoder boundary: fail closed for all foreign input, then reopen only
+// Buffer loaders that are part of LayerPorter's supported input contract.
+// HEIF/AVIF decoding stays disabled until the bundled runtime is independently
+// verified with libheif >=1.23.4, the current advisory set is re-reviewed, and
+// input support is explicitly re-approved.
+sharp.block({ operation: ['VipsForeignLoad'] });
+sharp.unblock({ operation: ALLOWED_UNTRUSTED_BUFFER_LOADERS });
+
 function assertBuffer(input) {
   if (!Buffer.isBuffer(input) || input.length === 0) {
     throw new TypeError('input must be a non-empty Buffer');
   }
 }
 
+function detectAllowedInputFormat(input) {
+  if (input.length >= 2 && input[0] === 0xff && input[1] === 0xd8) return 'jpeg';
+  if (input.length >= PNG_SIGNATURE.length && input.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) return 'png';
+  if (
+    input.length >= 12
+    && input.toString('ascii', 0, 4) === 'RIFF'
+    && input.toString('ascii', 8, 12) === 'WEBP'
+  ) return 'webp';
+  return null;
+}
+
+function assertAllowedInputFormat(input) {
+  const format = detectAllowedInputFormat(input);
+  if (format) return format;
+
+  const error = new TypeError('Unsupported or security-blocked input format; allowed input formats: JPEG, PNG, WebP');
+  error.code = 'INPUT_FORMAT_NOT_ALLOWED';
+  throw error;
+}
+
 function assertTarget(target = {}) {
   for (const key of ['width', 'height']) {
     if (target[key] !== undefined && (!Number.isInteger(target[key]) || target[key] < 1)) {
@@ -42,8 +78,32 @@ function encoder(pipeline, format, policy) {
   }
 }
 
+async function inspectEncodedOutput(data, info, outputFormat, policy) {
+  // HEIF/AVIF input is intentionally blocked in this process. For an AVIF we
+  // just encoded from an already validated input, use Sharp's encode result
+  // metadata instead of reopening the HEIF decoder. Independent fresh-process
+  // decode remains part of the regression/release gate.
+  if (outputFormat === 'avif') {
+    return {
+      format: 'avif',
+      hasAlpha: info.channels === 4,
+      orientation: null,
+      space: info.space ?? null,
+    };
+  }
+
+  const metadata = await sharp(data, { limitInputPixels: policy.maxPixels }).metadata();
+  return {
+    format: normalizeFormat(metadata.format, metadata.compression),
+    hasAlpha: Boolean(metadata.hasAlpha),
+    orientation: metadata.orientation ?? null,
+    space: metadata.space ?? null,
+  };
+}
+
 export async function inspectImage(input, options = {}) {
   assertBuffer(input);
+  assertAllowedInputFormat(input);
   const policy = validatePolicy(options.policy);
   const metadata = await sharp(input, { limitInputPixels: policy.maxPixels }).metadata();
 
@@ -139,7 +199,7 @@ export async function optimizeImage(input, options = {}) {
     };
   }
 
-  const outputMetadata = await sharp(data, { limitInputPixels: policy.maxPixels }).metadata();
+  const outputMetadata = await inspectEncodedOutput(data, info, outputFormat, policy);
   if (policy.preserveAlpha && original.hasAlpha && !outputMetadata.hasAlpha) {
     throw new Error('alpha preservation guard failed');
   }
@@ -150,12 +210,12 @@ export async function optimizeImage(input, options = {}) {
     original,
     output: {
       bytes: data.length,
-      format: normalizeFormat(outputMetadata.format, outputMetadata.compression),
+      format: outputMetadata.format,
       width: info.width,
       height: info.height,
-      hasAlpha: Boolean(outputMetadata.hasAlpha),
-      orientation: outputMetadata.orientation ?? null,
-      space: outputMetadata.space ?? null,
+      hasAlpha: outputMetadata.hasAlpha,
+      orientation: outputMetadata.orientation,
+      space: outputMetadata.space,
     },
     outputFormat,
     savingsBytes,

package/src/server.js

@@ -24,7 +24,7 @@ const OPEN_WORLD_READ_ANNOTATIONS = Object.freeze({
 export function createServer({ artifactStore = new ArtifactStore() } = {}) {
   const server = new McpServer({
     name: 'layerporter-image-optimizer',
-    version: '0.1.0',
+    version: '0.1.1',
     title: 'LayerPorter Website Image Optimizer',
     websiteUrl: 'https://layerporter.com/mcp/website-image-optimizer/',
   });