npm - @ampless/mcp-server - Versions diffs - 0.2.0-alpha.8 → 0.2.0-alpha.9 - Mend

@ampless/mcp-server 0.2.0-alpha.8 → 0.2.0-alpha.9

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.

Files changed (5) hide show

package/dist/{chunk-EGQ7Q3Y3.js → chunk-4PTNHZO4.js} +413 -1
package/dist/index.js +55 -1
package/dist/tools/index.d.ts +68 -1
package/dist/tools/index.js +5 -1
package/package.json +3 -2

package/dist/{chunk-EGQ7Q3Y3.js → chunk-4PTNHZO4.js} RENAMED Viewed

@@ -526,11 +526,379 @@ function getSchema() {
       editorTrust: 'editor stores arbitrary HTML/JS verbatim \u2014 same trust shape as WordPress unfiltered_html capability. See docs/architecture/04-access-layer-mcp.md \xA7"editor \u306E\u4FE1\u983C\u30E2\u30C7\u30EB".',
       tiptapBody: 'When format=tiptap, body is the tiptap document JSON: { type: "doc", content: [...] }. The renderer expects this shape.',
       noLayout: "metadata.no_layout=true serves the post as bare HTML with no theme chrome \u2014 the public route at /<slug> 302-redirects to /raw/<slug>, and that route renders the body verbatim with no wrapping <html>/<head>/layout. Use this for landing pages, embeds, or any post whose body is a full HTML document. Only meaningful with format=html (the other formats need the theme renderer).",
-      staticFormat: "A fourth format value `static` exists on the underlying data model for posts whose body is a JSON manifest pointing to a pre-uploaded HTML/CSS/JS bundle in S3 at public/static/<siteId>/<slug>/. Static uploads currently only flow through the admin UI; the MCP `upload_media` tool writes to public/media/ and does not handle static bundles. Use the admin StaticUploader for now."
+      staticFormat: "A fourth format value `static` exists on the underlying data model for posts whose body is a JSON manifest pointing to a pre-uploaded HTML/CSS/JS bundle in S3 at public/static/<siteId>/<slug>/. Static posts are created/edited through the dedicated tools `upload_static_bundle` (zip in one shot), `upload_static_file` / `delete_static_file` (incremental per-file ops), and `commit_static_post` (rebuild the manifest from the current S3 prefix). `create_post` / `update_post` intentionally do NOT accept format=static \u2014 the bundle tools are the only supported entry point so the Post manifest stays in sync with the S3 prefix."
     }
   };
 }
+// src/tools/upload-static-bundle.ts
+import {
+  bundlePrefix,
+  mimeTypeFor,
+  pickDefaultEntrypoint,
+  validateBundle
+} from "ampless";
+// src/tools/static-bundle-extract.ts
+import { unzipSync, strFromU8 } from "fflate";
+import {
+  validateBundlePath,
+  stripCommonPrefix
+} from "ampless";
+var DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+function extractZipFromBuffer(buffer, opts = {}) {
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  const entries2 = unzipSync(buffer);
+  const files = [];
+  const issues = [];
+  let totalBytes = 0;
+  for (const [name, data] of Object.entries(entries2)) {
+    if (name.endsWith("/")) continue;
+    const reason = validateBundlePath(name);
+    if (reason) {
+      const silent = reason === "macOS resource fork" || reason === ".DS_Store junk" || reason === "Thumbs.db junk" || reason === "directory entry";
+      if (!silent) issues.push({ path: name, reason });
+      continue;
+    }
+    totalBytes += data.byteLength;
+    if (totalBytes > maxBytes) {
+      throw new Error(
+        `Bundle too large: uncompressed size exceeds the ${Math.round(maxBytes / 1024 / 1024)} MB ceiling.`
+      );
+    }
+    files.push({ path: name, data });
+  }
+  return { files: stripCommonPrefix(files), issues, totalBytes };
+}
+function decodeUtf8(data) {
+  return strFromU8(data);
+}
+// src/tools/upsert-static-post.ts
+import {
+  composeSiteIdStatus as composeSiteIdStatus3,
+  composeSiteIdSlug as composeSiteIdSlug3,
+  encodeAwsJson as encodeAwsJson3
+} from "ampless";
+var CREATE_MUTATION = (
+  /* GraphQL */
+  `
+  ${POST_FIELDS}
+  mutation CreatePost($input: CreatePostInput!) {
+    createPost(input: $input) {
+      ...PostFields
+    }
+  }
+`
+);
+var UPDATE_MUTATION = (
+  /* GraphQL */
+  `
+  ${POST_FIELDS}
+  mutation UpdatePost($input: UpdatePostInput!) {
+    updatePost(input: $input) {
+      ...PostFields
+    }
+  }
+`
+);
+async function upsertStaticPost(graphql, siteId, slug, body, fields) {
+  const existing = await getPost(graphql, siteId, { siteId, slug });
+  if (existing) {
+    const input2 = {
+      siteId,
+      postId: existing.postId,
+      format: "static",
+      body: encodeAwsJson3(body)
+    };
+    if (fields.title !== void 0) input2.title = fields.title;
+    if (fields.excerpt !== void 0) input2.excerpt = fields.excerpt;
+    if (fields.status !== void 0) {
+      input2.status = fields.status;
+      input2.siteIdStatus = composeSiteIdStatus3(siteId, fields.status);
+    }
+    if (fields.publishedAt !== void 0) input2.publishedAt = fields.publishedAt;
+    if (fields.tags !== void 0) input2.tags = fields.tags;
+    if (fields.metadata !== void 0) {
+      input2.metadata = encodeAwsJson3(fields.metadata);
+    }
+    const data2 = await graphql.query(UPDATE_MUTATION, { input: input2 });
+    const updated = toCorePost(data2.updatePost);
+    await syncPostTags(graphql, updated, existing);
+    return { post: updated, created: false };
+  }
+  if (!fields.title) {
+    throw new Error(
+      `commit_static_post: cannot create a new post at slug "${slug}" without a title. Pass \`title\` or commit against an existing post.`
+    );
+  }
+  const status = fields.status ?? "draft";
+  const publishedAt = fields.publishedAt ?? (status === "published" ? (/* @__PURE__ */ new Date()).toISOString() : void 0);
+  const postId = fields.postId ?? `post-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const input = {
+    siteId,
+    postId,
+    slug,
+    title: fields.title,
+    format: "static",
+    body: encodeAwsJson3(body),
+    status,
+    siteIdStatus: composeSiteIdStatus3(siteId, status),
+    siteIdSlug: composeSiteIdSlug3(siteId, slug)
+  };
+  if (fields.excerpt !== void 0) input.excerpt = fields.excerpt;
+  if (publishedAt !== void 0) input.publishedAt = publishedAt;
+  if (fields.tags !== void 0) input.tags = fields.tags;
+  if (fields.metadata !== void 0) input.metadata = encodeAwsJson3(fields.metadata);
+  const data = await graphql.query(CREATE_MUTATION, { input });
+  const created = toCorePost(data.createPost);
+  await syncPostTags(graphql, created, null);
+  return { post: created, created: true };
+}
+// src/tools/upload-static-bundle.ts
+var uploadStaticBundleSchema = {
+  type: "object",
+  required: ["slug", "title", "zipBase64"],
+  properties: {
+    siteId: { type: "string", description: 'Site identifier (defaults to "default")' },
+    postId: {
+      type: "string",
+      description: "Optional explicit Post id when creating a new post. Ignored if a post at this slug already exists."
+    },
+    slug: { type: "string", description: "URL slug. Doubles as the S3 bundle path key." },
+    title: { type: "string" },
+    zipBase64: {
+      type: "string",
+      description: "Base64-encoded zip archive. NO `data:` URL prefix. Every entry must reference others by RELATIVE path; absolute paths (`/foo`) and protocol-relative URLs (`//cdn/foo`) inside HTML / CSS / SVG are rejected as the bundle would not be portable across URL prefixes."
+    },
+    entrypoint: {
+      type: "string",
+      description: "Relative path to the file served at the post URL (default `index.html`, or the first `.html` at root if `index.html` is absent)."
+    },
+    status: { type: "string", enum: ["draft", "published"], default: "draft" },
+    excerpt: { type: "string" },
+    publishedAt: { type: "string", description: 'ISO 8601 timestamp; defaults to "now" when status=published.' },
+    tags: { type: "array", items: { type: "string" } },
+    metadata: {
+      type: "object",
+      description: "Free-form per-post metadata. NOTE: `no_layout` is irrelevant for static posts (the bundle is already served raw).",
+      additionalProperties: true
+    }
+  }
+};
+async function uploadStaticBundle(graphql, storage, defaultSiteId, args) {
+  const siteId = args.siteId ?? defaultSiteId;
+  const slug = args.slug;
+  const zipBytes = Buffer.from(args.zipBase64, "base64");
+  if (zipBytes.length === 0) {
+    throw new Error("upload_static_bundle: zipBase64 decoded to zero bytes.");
+  }
+  const { files, issues } = extractZipFromBuffer(zipBytes);
+  if (issues.length > 0) {
+    throw new Error(
+      `upload_static_bundle: rejected bundle path(s): ${issues.map((i) => `${i.path} (${i.reason})`).join("; ")}`
+    );
+  }
+  if (files.length === 0) {
+    throw new Error("upload_static_bundle: zip contained no files.");
+  }
+  const contentIssues = validateBundle(files);
+  if (contentIssues.length > 0) {
+    throw new Error(
+      `upload_static_bundle: bundle contains absolute / protocol-relative refs: ${contentIssues.map((i) => `${i.path}: ${i.reason}`).join("; ")}`
+    );
+  }
+  const entrypoint = args.entrypoint ?? pickDefaultEntrypoint(files);
+  if (!files.some((f) => f.path === entrypoint)) {
+    throw new Error(
+      `upload_static_bundle: entrypoint "${entrypoint}" is not present in the bundle.`
+    );
+  }
+  const prefix = bundlePrefix(siteId, slug);
+  const existing = await storage.listObjects(prefix).catch((err) => {
+    console.error("[upload_static_bundle] listObjects failed (proceeding)", err);
+    return [];
+  });
+  for (const obj of existing) {
+    await storage.deleteObject(obj.key);
+  }
+  let uploadedFiles = 0;
+  for (const f of files) {
+    await storage.putObject(`${prefix}${f.path}`, f.data, mimeTypeFor(f.path));
+    uploadedFiles += 1;
+  }
+  const body = {
+    entrypoint,
+    files: files.map((f) => f.path).sort(),
+    uploadedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const { post } = await upsertStaticPost(graphql, siteId, slug, body, {
+    title: args.title,
+    postId: args.postId,
+    status: args.status,
+    publishedAt: args.publishedAt,
+    excerpt: args.excerpt,
+    tags: args.tags,
+    metadata: args.metadata
+  });
+  return { post, bundle: body, uploadedFiles };
+}
+// src/tools/upload-static-file.ts
+import {
+  bundlePrefix as bundlePrefix2,
+  findAbsolutePathRefs,
+  mimeTypeFor as mimeTypeFor2,
+  validateBundlePath as validateBundlePath2,
+  TEXT_EXTENSIONS
+} from "ampless";
+var uploadStaticFileSchema = {
+  type: "object",
+  required: ["slug", "filename", "base64Data"],
+  properties: {
+    siteId: { type: "string", description: 'Site identifier (defaults to "default")' },
+    slug: { type: "string", description: "Bundle slug. Files land at public/static/<siteId>/<slug>/<filename>." },
+    filename: {
+      type: "string",
+      description: "Relative path inside the bundle. Must NOT start with `/`, contain `..`, or include null bytes. macOS / Windows zip junk (`.DS_Store`, `__MACOSX/*`, `Thumbs.db`) is also rejected."
+    },
+    contentType: {
+      type: "string",
+      description: "IANA media type. Omit to derive from the filename extension (text/html, text/css, application/javascript, image/* \u2026; falls back to application/octet-stream)."
+    },
+    base64Data: {
+      type: "string",
+      description: "Base64-encoded file bytes. NO `data:` URL prefix. Text files (HTML/CSS/SVG) are linted for absolute / protocol-relative URL refs \u2014 failures throw."
+    }
+  }
+};
+async function uploadStaticFile(storage, defaultSiteId, args) {
+  const siteId = args.siteId ?? defaultSiteId;
+  const filename = args.filename;
+  const reason = validateBundlePath2(filename);
+  if (reason) {
+    throw new Error(`upload_static_file: invalid filename "${filename}" (${reason})`);
+  }
+  const body = Buffer.from(args.base64Data, "base64");
+  if (body.length === 0) {
+    throw new Error("upload_static_file: base64Data decoded to zero bytes.");
+  }
+  const ext = filename.toLowerCase().slice(filename.lastIndexOf("."));
+  if (TEXT_EXTENSIONS.has(ext)) {
+    const text = body.toString("utf8");
+    const issues = findAbsolutePathRefs(filename, text);
+    if (issues.length > 0) {
+      throw new Error(
+        `upload_static_file: ${filename} contains absolute / protocol-relative refs: ${issues.map((i) => i.reason).join("; ")}`
+      );
+    }
+  }
+  const contentType = args.contentType ?? mimeTypeFor2(filename);
+  const key = `${bundlePrefix2(siteId, args.slug)}${filename}`;
+  const url = await storage.putObject(key, body, contentType);
+  return { key, url, size: body.length };
+}
+// src/tools/delete-static-file.ts
+import { bundlePrefix as bundlePrefix3, validateBundlePath as validateBundlePath3 } from "ampless";
+var deleteStaticFileSchema = {
+  type: "object",
+  required: ["slug", "filename"],
+  properties: {
+    siteId: { type: "string", description: 'Site identifier (defaults to "default")' },
+    slug: { type: "string" },
+    filename: {
+      type: "string",
+      description: "Relative path inside the bundle to delete. Same path rules as `upload_static_file` apply (no `..`, no absolute paths, no null bytes)."
+    }
+  }
+};
+async function deleteStaticFile(storage, defaultSiteId, args) {
+  const siteId = args.siteId ?? defaultSiteId;
+  const reason = validateBundlePath3(args.filename);
+  if (reason) {
+    throw new Error(`delete_static_file: invalid filename "${args.filename}" (${reason})`);
+  }
+  const prefix = bundlePrefix3(siteId, args.slug);
+  const key = `${prefix}${args.filename}`;
+  const existing = await storage.listObjects(key);
+  const found = existing.some((o) => o.key === key);
+  if (!found) {
+    return { key, deleted: false };
+  }
+  await storage.deleteObject(key);
+  return { key, deleted: true };
+}
+// src/tools/commit-static-post.ts
+import {
+  bundlePrefix as bundlePrefix4,
+  pickDefaultEntrypoint as pickDefaultEntrypoint2
+} from "ampless";
+var commitStaticPostSchema = {
+  type: "object",
+  required: ["slug"],
+  properties: {
+    siteId: { type: "string", description: 'Site identifier (defaults to "default")' },
+    slug: { type: "string" },
+    title: {
+      type: "string",
+      description: "Required when this is a brand-new post (no existing row at the slug). On update, falls back to the current title."
+    },
+    entrypoint: {
+      type: "string",
+      description: "Relative path of the entry file (defaults to `index.html`, or the first `.html` at root if absent). Must exist under the current S3 prefix."
+    },
+    postId: {
+      type: "string",
+      description: "Optional explicit Post id when creating a new post. Ignored if a row at this slug already exists."
+    },
+    status: { type: "string", enum: ["draft", "published"] },
+    publishedAt: { type: "string", description: "ISO 8601 timestamp." },
+    excerpt: { type: "string" },
+    tags: { type: "array", items: { type: "string" } },
+    metadata: {
+      type: "object",
+      description: "Free-form per-post metadata. Passing this REPLACES the existing object on update.",
+      additionalProperties: true
+    }
+  }
+};
+async function commitStaticPost(graphql, storage, defaultSiteId, args) {
+  const siteId = args.siteId ?? defaultSiteId;
+  const slug = args.slug;
+  const prefix = bundlePrefix4(siteId, slug);
+  const objects = await storage.listObjects(prefix);
+  if (objects.length === 0) {
+    throw new Error(
+      `commit_static_post: no files found under "${prefix}". Upload at least one file via upload_static_file or upload_static_bundle before committing.`
+    );
+  }
+  const relPaths = objects.map((o) => o.key.slice(prefix.length)).filter((p) => p !== "").sort();
+  const entrypoint = args.entrypoint ?? pickDefaultEntrypoint2(relPaths.map((p) => ({ path: p })));
+  if (!relPaths.includes(entrypoint)) {
+    throw new Error(
+      `commit_static_post: entrypoint "${entrypoint}" is not present under "${prefix}".`
+    );
+  }
+  const body = {
+    entrypoint,
+    files: relPaths,
+    uploadedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const { post, created } = await upsertStaticPost(graphql, siteId, slug, body, {
+    title: args.title,
+    postId: args.postId,
+    excerpt: args.excerpt,
+    status: args.status,
+    publishedAt: args.publishedAt,
+    tags: args.tags,
+    metadata: args.metadata
+  });
+  return { post, bundle: body, created };
+}
 // src/tools/index.ts
 var tools = [
   {
@@ -574,6 +942,48 @@ var tools = [
     description: "Returns the CMS content schema (Post/Page/Media field shapes, format enum, notes). Useful as the first call to understand what fields are available.",
     inputSchema: getSchemaSchema,
     handler: async () => getSchema()
+  },
+  {
+    name: "upload_static_bundle",
+    description: "Create or replace a `format: 'static'` post in one shot. Pass a base64-encoded zip; the server unpacks it, validates every path + lints HTML/CSS/SVG for absolute path refs (bundles must be self-contained via relative paths), wipes the existing S3 prefix at public/static/<siteId>/<slug>/, uploads every file, and upserts the Post row with a manifest pointing at the entrypoint. Use this when you have the whole bundle to submit at once. For incremental edits use upload_static_file / delete_static_file followed by commit_static_post.",
+    inputSchema: uploadStaticBundleSchema,
+    handler: (args, ctx) => uploadStaticBundle(
+      ctx.graphql,
+      ctx.storage(),
+      ctx.defaultSiteId,
+      args
+    )
+  },
+  {
+    name: "upload_static_file",
+    description: "Upload a single file into an existing static bundle's S3 prefix. The Post row is NOT modified \u2014 its `body` manifest will be out of sync with the prefix until you call `commit_static_post`. Use this for incremental edits (one CSS swap, single image change) where rebuilding the entire zip would be overkill. Text files (HTML/CSS/SVG) are linted for absolute / protocol-relative URL refs the same as the zip flow.",
+    inputSchema: uploadStaticFileSchema,
+    handler: (args, ctx) => uploadStaticFile(
+      ctx.storage(),
+      ctx.defaultSiteId,
+      args
+    )
+  },
+  {
+    name: "delete_static_file",
+    description: "Delete a single file from a static bundle's S3 prefix. The Post row is NOT modified \u2014 its `body` manifest will list the deleted file until you call `commit_static_post`. Idempotent: returns `{ deleted: false }` instead of throwing if the file isn't there.",
+    inputSchema: deleteStaticFileSchema,
+    handler: (args, ctx) => deleteStaticFile(
+      ctx.storage(),
+      ctx.defaultSiteId,
+      args
+    )
+  },
+  {
+    name: "commit_static_post",
+    description: 'Rebuild a static post\'s Post row from whatever is currently in its S3 prefix. Scans `public/static/<siteId>/<slug>/`, picks the entrypoint (default `index.html` or override), and upserts the Post with a fresh manifest (sorted file list + uploadedAt timestamp). Use this as the "save" step after a series of `upload_static_file` / `delete_static_file` calls. `title` is required when creating a brand-new post; on update, existing fields are preserved unless explicitly overridden.',
+    inputSchema: commitStaticPostSchema,
+    handler: (args, ctx) => commitStaticPost(
+      ctx.graphql,
+      ctx.storage(),
+      ctx.defaultSiteId,
+      args
+    )
   }
 ];
 async function dispatchToolCall(name, args, ctx) {
@@ -586,6 +996,8 @@ function getTools() {
 }
 export {
+  extractZipFromBuffer,
+  decodeUtf8,
   tools,
   dispatchToolCall,
   getTools

package/dist/index.js CHANGED Viewed

@@ -7,7 +7,7 @@ import {
 } from "./chunk-IW52OUIR.js";
 import {
   tools
-} from "./chunk-EGQ7Q3Y3.js";
+} from "./chunk-4PTNHZO4.js";
 import {
   AwsCrc32,
   __awaiter,
@@ -32067,6 +32067,32 @@ function isValidBase64EncodedSSECustomerKey(str, options) {
   }
 }
+// ../../node_modules/.pnpm/@aws-sdk+client-s3@3.1048.0/node_modules/@aws-sdk/client-s3/dist-es/commands/DeleteObjectCommand.js
+var DeleteObjectCommand = class extends Command.classBuilder().ep({
+  ...commonParams,
+  Bucket: { type: "contextParams", name: "Bucket" },
+  Key: { type: "contextParams", name: "Key" }
+}).m(function(Command2, cs, config2, o2) {
+  return [
+    getEndpointPlugin(config2, Command2.getEndpointParameterInstructions()),
+    getThrow200ExceptionsPlugin(config2)
+  ];
+}).s("AmazonS3", "DeleteObject", {}).n("S3Client", "DeleteObjectCommand").sc(DeleteObject$).build() {
+};
+// ../../node_modules/.pnpm/@aws-sdk+client-s3@3.1048.0/node_modules/@aws-sdk/client-s3/dist-es/commands/ListObjectsV2Command.js
+var ListObjectsV2Command = class extends Command.classBuilder().ep({
+  ...commonParams,
+  Bucket: { type: "contextParams", name: "Bucket" },
+  Prefix: { type: "contextParams", name: "Prefix" }
+}).m(function(Command2, cs, config2, o2) {
+  return [
+    getEndpointPlugin(config2, Command2.getEndpointParameterInstructions()),
+    getThrow200ExceptionsPlugin(config2)
+  ];
+}).s("AmazonS3", "ListObjectsV2", {}).n("S3Client", "ListObjectsV2Command").sc(ListObjectsV2$).build() {
+};
 // ../../node_modules/.pnpm/@aws-sdk+client-s3@3.1048.0/node_modules/@aws-sdk/client-s3/dist-es/commands/PutObjectCommand.js
 var PutObjectCommand = class extends Command.classBuilder().ep({
   ...commonParams,
@@ -32113,6 +32139,34 @@ var StorageClient = class {
     );
     return formatPublicAssetUrl(this.bucket, this.region, key);
   }
+  async deleteObject(key) {
+    await this.client.send(
+      new DeleteObjectCommand({ Bucket: this.bucket, Key: key })
+    );
+  }
+  async listObjects(prefix) {
+    const out = [];
+    let token;
+    do {
+      const res = await this.client.send(
+        new ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: prefix,
+          ContinuationToken: token
+        })
+      );
+      for (const obj of res.Contents ?? []) {
+        if (!obj.Key) continue;
+        out.push({
+          key: obj.Key,
+          size: obj.Size ?? 0,
+          lastModified: obj.LastModified?.toISOString()
+        });
+      }
+      token = res.IsTruncated ? res.NextContinuationToken : void 0;
+    } while (token);
+    return out;
+  }
 };
 // src/server.ts

package/dist/tools/index.d.ts CHANGED Viewed

@@ -1,3 +1,5 @@
+import { BundleExtractResult } from 'ampless';
 /**
  * Abstract contracts each tool handler depends on. Concrete
  * implementations live elsewhere:
@@ -15,6 +17,14 @@
 interface GraphqlClient {
     query<T>(operation: string, variables?: Record<string, unknown>): Promise<T>;
 }
+interface StorageObject {
+    /** Full S3 key including any prefix. */
+    key: string;
+    /** Object size in bytes (0 when the backend can't supply it). */
+    size: number;
+    /** ISO 8601 timestamp of the last write, when the backend supplies it. */
+    lastModified?: string;
+}
 interface StorageClient {
     /**
      * Upload `body` to the bucket at `key` with `contentType`. Returns
@@ -22,6 +32,18 @@ interface StorageClient {
      * https://{bucket}.s3.{region}.amazonaws.com/{key}).
      */
     putObject(key: string, body: Uint8Array, contentType: string): Promise<string>;
+    /**
+     * Remove the object at `key`. Implementations should treat a missing
+     * key as success (S3 DeleteObject is idempotent by default).
+     */
+    deleteObject(key: string): Promise<void>;
+    /**
+     * List every object under `prefix`. Implementations are expected to
+     * paginate internally so the caller gets the full set in a single
+     * resolved promise — the static-bundle tools never expect more than
+     * a few hundred entries per bundle in practice.
+     */
+    listObjects(prefix: string): Promise<StorageObject[]>;
 }
 interface ToolContext {
     graphql: GraphqlClient;
@@ -29,6 +51,51 @@ interface ToolContext {
     defaultSiteId: string;
 }
+/**
+ * Server-side zip extractor used by the static-bundle MCP tools. Both
+ * the stdio CLI and the Lambda HTTP transport run this — `fflate` is
+ * a workspace dependency of `@ampless/mcp-server`, so the import
+ * resolves identically in both. The browser-side admin uploader has
+ * its own `extractZip(File)` based on JSZip (works on a `File`, not a
+ * `Buffer`).
+ *
+ * Behaviour parity with the admin extractor:
+ *  - Skip directory entries (fflate gives byte arrays only, so this
+ *    is naturally satisfied unless the zip has empty-byte directory
+ *    placeholders — those still get filtered out by validateBundlePath
+ *    returning "directory entry" for any path ending with `/`).
+ *  - Silently drop OS-specific junk (`__MACOSX/*`, `.DS_Store`,
+ *    `Thumbs.db`) so callers don't see them as bundle entries.
+ *  - Surface structural issues (absolute paths, parent traversal, null
+ *    bytes) so the tool can reject the upload.
+ *  - Strip a common single top-level directory (macOS Finder zips
+ *    wrap their contents in a folder).
+ */
+interface ExtractZipOptions {
+    /**
+     * Hard ceiling on uncompressed bundle bytes. Defaults to 50 MB,
+     * matching the browser uploader's MAX_BUNDLE_BYTES. Callers running
+     * inside a tight Lambda envelope (Function URL payload cap ~6 MB
+     * post-base64) can tighten this; setting it lower than the bundle
+     * causes `extractZipFromBuffer` to throw before fully populating
+     * `files`.
+     */
+    maxBytes?: number;
+}
+/**
+ * Unzip `buffer` in memory and return the same shape the browser
+ * `extractZip(File)` helper returns. Throws if the unzip itself fails
+ * (corrupt archive) or if the uncompressed size exceeds `maxBytes`.
+ */
+declare function extractZipFromBuffer(buffer: Uint8Array, opts?: ExtractZipOptions): BundleExtractResult;
+/**
+ * Decode an extracted file's bytes as UTF-8 text. Used by the tool
+ * handler before running cross-file `validateBundle` so we don't
+ * instantiate a TextDecoder per entry. fflate provides a fast helper.
+ */
+declare function decodeUtf8(data: Uint8Array): string;
 interface ToolDefinition {
     name: string;
     description: string;
@@ -49,4 +116,4 @@ declare function dispatchToolCall(name: string, args: Record<string, unknown>, c
  */
 declare function getTools(): readonly ToolDefinition[];
-export { type GraphqlClient, type StorageClient, type ToolContext, type ToolDefinition, dispatchToolCall, getTools, tools };
+export { type ExtractZipOptions, type GraphqlClient, type StorageClient, type StorageObject, type ToolContext, type ToolDefinition, decodeUtf8, dispatchToolCall, extractZipFromBuffer, getTools, tools };

package/dist/tools/index.js CHANGED Viewed

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import {
+  decodeUtf8,
   dispatchToolCall,
+  extractZipFromBuffer,
   getTools,
   tools
-} from "../chunk-EGQ7Q3Y3.js";
+} from "../chunk-4PTNHZO4.js";
 import "../chunk-LMMQX4CK.js";
 export {
+  decodeUtf8,
   dispatchToolCall,
+  extractZipFromBuffer,
   getTools,
   tools
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/mcp-server",
-  "version": "0.2.0-alpha.8",
+  "version": "0.2.0-alpha.9",
   "description": "MCP server for ampless — lets AI agents (Claude Desktop, Cursor, Claude Code) read and write posts and media via AppSync",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,8 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@aws-sdk/client-s3": "^3.1048.0",
     "amazon-cognito-identity-js": "^6.3.12",
-    "ampless": "0.2.0-alpha.7"
+    "fflate": "^0.8.2",
+    "ampless": "0.2.0-alpha.8"
   },
   "keywords": [
     "ampless",