@buildinternet/uploads 0.11.0 → 0.11.1

package/dist/mcp/batch-error.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tool handler failure that still carries structuredContent (e.g. multi-file
+ * total failure with a `failures` array). The MCP server maps this to
+ * isError: true while preserving structuredContent for agents.
+ */
+export declare class ToolBatchError extends Error {
+    readonly structuredContent: unknown;
+    constructor(message: string, structuredContent: unknown);
+}
+/** One-line summary of a multi-file failure list. */
+export declare function batchFailureMessage(failures: readonly {
+    file: string;
+    error: {
+        message: string;
+    };
+}[]): string;

package/dist/mcp/batch-error.js

@@ -0,0 +1,24 @@
+/**
+ * Tool handler failure that still carries structuredContent (e.g. multi-file
+ * total failure with a `failures` array). The MCP server maps this to
+ * isError: true while preserving structuredContent for agents.
+ */
+export class ToolBatchError extends Error {
+    structuredContent;
+    constructor(message, structuredContent) {
+        super(message);
+        this.name = "ToolBatchError";
+        this.structuredContent = structuredContent;
+    }
+}
+/** One-line summary of a multi-file failure list. */
+export function batchFailureMessage(failures) {
+    if (failures.length === 0)
+        return "upload failed";
+    if (failures.length === 1) {
+        const f = failures[0];
+        return `${f.file}: ${f.error.message}`;
+    }
+    const lines = failures.map((f) => `  ${f.file}: ${f.error.message}`);
+    return `${failures.length} uploads failed:\n${lines.join("\n")}`;
+}

package/dist/mcp/server.d.ts

@@ -1,4 +1,5 @@
 export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
+export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 export interface McpTool {
     name: string;
     description: string;

package/dist/mcp/server.js

@@ -9,7 +9,9 @@
  */
 import { UploadsError } from "../errors.js";
 import { errorCodeFromUnknown, recordEvent } from "../telemetry.js";
+import { ToolBatchError } from "./batch-error.js";
 export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
+export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
 const LATEST_PROTOCOL_VERSION = "2025-06-18";
 function response(id, result) {
@@ -59,6 +61,20 @@ export function createMcpServer(opts) {
                 durationMs: Date.now() - start,
                 errorCode: errorCodeFromUnknown(err),
             }, { apiUrl });
+            // Multi-file total failure: keep structuredContent so agents see every
+            // per-file error, not only the first message string.
+            if (err instanceof ToolBatchError) {
+                return response(id, {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(err.structuredContent, null, 2),
+                        },
+                    ],
+                    structuredContent: err.structuredContent,
+                    isError: true,
+                });
+            }
             return response(id, {
                 content: [{ type: "text", text: toolErrorText(err) }],
                 isError: true,

package/dist/mcp/tools.d.ts

@@ -2,7 +2,7 @@ import type { GlobalFlags } from "../cli-args.js";
 import { type UploadsClient } from "../client.js";
 import { type UploadsClientConfig } from "../config.js";
 import { type CommandRunner } from "../github-gh.js";
-import type { McpTool } from "./server.js";
+import { type McpTool } from "./server.js";
 export declare function createUploadsMcpTools(opts: {
     globals: GlobalFlags;
     runner?: CommandRunner;

package/dist/mcp/tools.js

@@ -1,13 +1,5 @@
-/**
- * MCP tool set mirroring the CLI commands (put, attach, list, delete,
- * usage, reconcile, purge_expired, comment, health, doctor). Config is
- * resolved fresh per tool call so a
- * per-call `workspace` argument behaves like the CLI's --workspace flag, and
- * a missing token surfaces as a tool error rather than a startup failure.
- */
-import { basename } from "node:path";
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, prepareImageForUpload, readFileArg, syncAttachmentsComment, } from "../commands.js";
+import { buildDoctorReport, makeGhTarget, prepareImageForUpload, syncAttachmentsComment, uploadAttachments, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { buildMarkdown } from "../embed.js";
@@ -19,6 +11,7 @@ import { rewriteKeyExtension } from "../optimize.js";
 import { buildCliProvenance } from "../provenance.js";
 import { execRunner, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
 import { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
+import { batchFailureMessage, ToolBatchError } from "./server.js";
 import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
 import { resolveApiUrl } from "../config.js";
 function optBool(args, name) {
@@ -270,13 +263,18 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "put",
-            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown. Returns `url` (durable CDN) and `embedUrl` (same object, freshness-oriented host for GitHub Camo — prefer this in PR/issue markdown). The returned `markdown` already uses embedUrl when available. Pass `file` or `contentBase64` + `filename`; with `pr`/`issue` the key is stable and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable, so upload only non-sensitive media.",
+            description: "Upload one or more files to uploads.sh and get public URL(s) plus GitHub-ready embed markdown. Single-file: pass `file` or `contentBase64`+`filename` (flat result with `url`/`embedUrl`/`markdown`). Multi-file: pass `files` (paths; parallel; returns `uploads`+`failures`). Prefer `embedUrl` in PR/issue markdown. With `pr`/`issue` keys are stable and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable — upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
                     file: {
                         type: "string",
-                        description: "Path of the file to upload. Exactly one of file or contentBase64 is required.",
+                        description: "Path of a single file to upload. Exactly one of file, files, or contentBase64 is required.",
+                    },
+                    files: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Paths of multiple files to upload in parallel. Returns { uploads, failures }. Cannot combine with file, contentBase64, key, or filename.",
                     },
                     contentBase64: {
                         type: "string",
@@ -284,11 +282,11 @@ export function createUploadsMcpTools(opts) {
                     },
                     filename: {
                         type: "string",
-                        description: "Filename for contentBase64 content (drives the key and content type). With `file`, overrides the key's leaf (clean name) while keeping the pr/default path.",
+                        description: "Filename for contentBase64 content (drives the key and content type). With single `file`, overrides the key's leaf (clean name) while keeping the pr/default path.",
                     },
                     key: {
                         type: "string",
-                        description: "Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>). Cannot be combined with pr/issue.",
+                        description: "Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>). Single file only; cannot be combined with pr/issue.",
                     },
                     destination: {
                         type: "string",
@@ -308,7 +306,10 @@ export function createUploadsMcpTools(opts) {
                         type: "string",
                         description: "PR/issue/branch key segment (default: today, or UPLOADS_DEFAULT_REF). Cannot be combined with pr/issue.",
                     },
-                    alt: { type: "string", description: "Alt text for the markdown (default: filename)." },
+                    alt: {
+                        type: "string",
+                        description: "Alt text for the markdown (default: each file's name; with multiple files applies to all).",
+                    },
                     width: {
                         type: "number",
                         description: "Emit <img width=…> markdown instead of a plain image embed.",
@@ -350,14 +351,24 @@ export function createUploadsMcpTools(opts) {
             },
             async handler(args) {
                 const file = optString(args, "file");
+                const filesArg = optStringArray(args, "files");
                 const contentBase64 = optString(args, "contentBase64");
-                if ((file === undefined) === (contentBase64 === undefined)) {
-                    usage("exactly one of file or contentBase64 is required");
+                if (filesArg !== undefined && filesArg.length === 0) {
+                    usage("files must be a non-empty array of paths");
+                }
+                const multi = filesArg !== undefined;
+                const sources = [file !== undefined, multi, contentBase64 !== undefined];
+                if (sources.filter(Boolean).length !== 1) {
+                    usage("exactly one of file, files, or contentBase64 is required");
                 }
                 const filenameArg = optString(args, "filename");
                 if (contentBase64 !== undefined && !filenameArg) {
                     usage("filename is required with contentBase64");
                 }
+                if (multi && filenameArg)
+                    usage("filename cannot be combined with files");
+                if (multi && optString(args, "key"))
+                    usage("key cannot be combined with files");
                 const target = ghTargetFromArgs(args, run);
                 const wantComment = optBool(args, "comment");
                 const dryRun = optBool(args, "dryRun");
@@ -396,67 +407,130 @@ export function createUploadsMcpTools(opts) {
                     usage(err instanceof Error ? err.message : String(err));
                 }
                 const { client } = clientFor(args);
-                const bytes = file !== undefined
-                    ? readFileArg(file)
-                    : new Uint8Array(Buffer.from(contentBase64, "base64"));
-                const sourceName = file !== undefined ? (filenameArg ?? basename(file)) : filenameArg;
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
-                const prepared = await prepareImageForUpload(bytes, sourceName, {
-                    ...frameOpts,
-                    optimize: optimizeOpts,
-                });
-                const filename = prepared.filename;
-                let key = target ? ghAttachmentKey(target, filename) : keyArg;
-                if (key && prepared.optimized)
-                    key = rewriteKeyExtension(key, filename);
                 const noGit = optBool(args, "noGit") || defaults.noGit === true;
-                const result = await client.put(prepared.bytes, {
-                    filename,
-                    key,
+                const alt = optString(args, "alt");
+                const width = optPosInt(args, "width") ?? defaults.width;
+                const contentType = optString(args, "contentType");
+                const putShared = {
+                    client,
+                    ghTarget: target,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
                     ref: refArg ?? defaults.ref,
-                    contentType: prepared.optimized ? prepared.contentType : optString(args, "contentType"),
                     deriveRepoFromGit: !noGit,
+                    contentType,
                     dryRun,
-                    provenance: buildCliProvenance({
-                        sourceName,
-                        client: "uploads-mcp",
-                        optimized: prepared.optimized,
-                        frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
-                        keepExif: optimizeOpts.keepExif === true,
-                    }),
+                    optimize: optimizeOpts,
+                    frame: frameOpts,
                     metadata,
+                    provenanceClient: "uploads-mcp",
+                    alt,
+                    width,
+                };
+                // Multi-file path (paths only — no base64 batch).
+                if (multi) {
+                    const { uploads, failures } = await uploadPuts({
+                        ...putShared,
+                        files: filesArg,
+                    });
+                    if (uploads.length === 0 && failures.length > 0) {
+                        throw new ToolBatchError(batchFailureMessage(failures), { uploads, failures });
+                    }
+                    if (wantComment && target && uploads.length > 0) {
+                        const { comment, commentError } = await syncComment(client, target);
+                        return { uploads, failures, comment, commentError };
+                    }
+                    return { uploads, failures };
+                }
+                // Single-file: contentBase64 still supported; paths go through uploadPuts.
+                if (contentBase64 !== undefined) {
+                    const sourceName = filenameArg;
+                    const bytes = new Uint8Array(Buffer.from(contentBase64, "base64"));
+                    const prepared = await prepareImageForUpload(bytes, sourceName, {
+                        ...frameOpts,
+                        optimize: optimizeOpts,
+                    });
+                    const filename = prepared.filename;
+                    let key = target ? ghAttachmentKey(target, filename) : keyArg;
+                    if (key && prepared.optimized)
+                        key = rewriteKeyExtension(key, filename);
+                    const result = await client.put(prepared.bytes, {
+                        filename,
+                        key,
+                        prefix: resolvedPrefix ?? defaults.prefix,
+                        repo: optString(args, "repo") ?? defaults.repo,
+                        ref: refArg ?? defaults.ref,
+                        contentType: prepared.optimized ? prepared.contentType : contentType,
+                        deriveRepoFromGit: !noGit,
+                        dryRun,
+                        provenance: buildCliProvenance({
+                            sourceName,
+                            client: "uploads-mcp",
+                            optimized: prepared.optimized,
+                            frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
+                            keepExif: optimizeOpts.keepExif === true,
+                        }),
+                        metadata,
+                    });
+                    const markdown = buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
+                        alt: alt ?? sourceName,
+                        width,
+                    });
+                    const optimize = {
+                        optimized: prepared.optimized,
+                        skippedReason: prepared.skippedReason,
+                        originalBytes: prepared.originalBytes,
+                        outputBytes: prepared.outputBytes,
+                        filename: prepared.filename,
+                    };
+                    if (wantComment && target) {
+                        const { comment, commentError } = await syncComment(client, target);
+                        return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
+                    }
+                    return {
+                        ...result,
+                        markdown,
+                        optimize,
+                        frame: prepared.frame,
+                        ...(dryRun ? { dryRun: true } : {}),
+                    };
+                }
+                const { uploads, failures, firstError } = await uploadPuts({
+                    ...putShared,
+                    files: [file],
+                    nameOverride: filenameArg,
+                    explicitKey: keyArg,
                 });
-                const markdown = buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
-                    alt: optString(args, "alt") ?? sourceName,
-                    width: optPosInt(args, "width") ?? defaults.width,
-                });
-                const optimize = {
-                    optimized: prepared.optimized,
-                    skippedReason: prepared.skippedReason,
-                    originalBytes: prepared.originalBytes,
-                    outputBytes: prepared.outputBytes,
-                    filename: prepared.filename,
+                if (uploads.length === 0 && failures.length > 0) {
+                    throw firstError instanceof Error ? firstError : new Error(String(firstError));
+                }
+                const u = uploads[0];
+                const flat = {
+                    workspace: u.workspace,
+                    key: u.key,
+                    url: u.url,
+                    embedUrl: u.embedUrl,
+                    size: u.size,
+                    contentType: u.contentType,
+                    replaced: u.replaced,
+                    markdown: u.markdown,
+                    optimize: u.optimize,
+                    frame: u.frame,
+                    ...(dryRun ? { dryRun: true } : {}),
                 };
                 if (wantComment && target) {
                     const { comment, commentError } = await syncComment(client, target);
-                    return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
+                    return { ...flat, comment, commentError };
                 }
-                return {
-                    ...result,
-                    markdown,
-                    optimize,
-                    frame: prepared.frame,
-                    ...(dryRun ? { dryRun: true } : {}),
-                };
+                return flat;
             },
         },
         {
             name: "attach",
-            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them. Each upload returns `url`, `embedUrl` (when dual-host applies), and `markdown` (uses embedUrl for GitHub). With no pr/issue, targets the pull request for the current branch. Attachments are public and keys are predictable; upload only non-sensitive media.",
+            description: "Upload one or more files as stable PR/issue attachments (in parallel) and maintain a managed GitHub comment. Returns `uploads` and `failures` (one bad file does not abort the batch). Each success has `url`, `embedUrl`, and `markdown` (prefer embedUrl for GitHub). With no pr/issue, targets the current branch PR. Attachments are public and keys are predictable; upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -523,45 +597,28 @@ export function createUploadsMcpTools(opts) {
                 const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
                 if (Object.keys(metadata).length > 0)
                     validateMetaMap(metadata);
-                const uploads = [];
-                for (const file of files) {
-                    const sourceName = basename(file);
-                    const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
-                        ...frameOpts,
-                        optimize: optimizeOpts,
-                    });
-                    const result = await client.put(prepared.bytes, {
-                        filename: prepared.filename,
-                        key: ghAttachmentKey(target, prepared.filename),
-                        contentType: prepared.optimized ? prepared.contentType : contentType,
-                        provenance: buildCliProvenance({
-                            sourceName,
-                            client: "uploads-mcp",
-                            optimized: prepared.optimized,
-                            frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
-                            keepExif: optimizeOpts.keepExif === true,
-                        }),
-                        metadata,
-                    });
-                    uploads.push({
-                        ...result,
-                        markdown: buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
-                            alt: sourceName,
-                        }),
-                        frame: prepared.frame,
-                        optimize: {
-                            optimized: prepared.optimized,
-                            skippedReason: prepared.skippedReason,
-                            originalBytes: prepared.originalBytes,
-                            outputBytes: prepared.outputBytes,
-                            filename: prepared.filename,
-                        },
+                const { uploads, failures } = await uploadAttachments({
+                    client,
+                    target,
+                    files,
+                    contentType,
+                    optimize: optimizeOpts,
+                    frame: frameOpts,
+                    metadata,
+                    provenanceClient: "uploads-mcp",
+                });
+                // Total failure → isError with full failures[] for agents.
+                if (uploads.length === 0 && failures.length > 0) {
+                    throw new ToolBatchError(batchFailureMessage(failures), {
+                        target,
+                        uploads,
+                        failures,
                     });
                 }
                 if (optBool(args, "noComment"))
-                    return { target, uploads };
+                    return { target, uploads, failures };
                 const { comment, commentError } = await syncComment(client, target);
-                return { target, uploads, comment, commentError };
+                return { target, uploads, failures, comment, commentError };
             },
         },
         {
@@ -628,9 +685,28 @@ export function createUploadsMcpTools(opts) {
                 return client.delete(key);
             },
         },
+        {
+            name: "get_metadata",
+            description: "Read an object's queryable custom metadata (D1 key-value pairs, not R2 provenance). Returns `{ metadata }` (empty when none). Object must exist. Same as `uploads meta get`.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "Object key to inspect." },
+                    workspace: workspaceProp,
+                },
+                required: ["key"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const key = optString(args, "key");
+                if (!key)
+                    usage("key is required");
+                return clientFor(args).client.getMetadata(key);
+            },
+        },
         {
             name: "set_metadata",
-            description: "Merge-set and/or delete an object's queryable custom metadata (D1-backed key-value pairs; distinct from the R2 provenance headers put on upload). `set` pairs win over `delete` when a key appears in both. " +
+            description: "Merge-set and/or delete an object's queryable custom metadata (D1 key-value pairs, not R2 provenance). `set` wins over `delete` for the same key. " +
                 METADATA_DESCRIPTION +
                 " Requires at least one of `set` or `delete`. Same as `uploads meta set`.",
             inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,