@buildinternet/uploads 0.1.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Build Internet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,9 +4,7 @@ CLI and client for **uploads.sh** — upload files, get public URLs, and produce
 
 ## CLI
 
-Binary: `uploads` (also `pnpm uploads` from repo root after `pnpm install`).
-
-Install globally or run a pinned version without installing:
+Binary: **`uploads`**. Install globally (or use a pinned `npx` one-shot):
 
 ```bash
 npm install --global @buildinternet/uploads
@@ -14,29 +12,65 @@ npx @buildinternet/uploads@0.1.0 --help
 ```
 
 ```bash
-pnpm uploads setup --env-file .env
-pnpm uploads attach ./before.png ./after.png --env-file .env
-pnpm uploads put ./shot.png --env-file .env
-pnpm uploads put ./after.png --pr 123 --comment --env-file .env
-pnpm uploads doctor --env-file .env
+uploads setup
+uploads attach ./before.png ./after.png
+uploads put ./shot.png
+uploads put ./shot.png --destination screenshots
+uploads put ./shot.png --no-optimize
+uploads put ./mobile.png --frame phone
+uploads put ./ui.png --frame browser --frame-url "https://app.example"
+uploads put ./after.png --pr 123 --comment
+uploads doctor
 ```
 
-Commands: `attach`, `put`, `comment`, `list`, `delete`, `setup`, `config`, `doctor`, `health`.
+Inside this monorepo only, `pnpm uploads …` builds the package first so you pick
+up local source; product docs and PR “how to try it” examples should use the
+global `uploads` form above.
+
+Commands: `attach`, `put`, `comment`, `list`, `delete`, `usage`, `reconcile`,
+`purge-expired`, `setup`, `install`, `config`, `doctor`, `health`, `mcp`.
 
 `attach` is the agent-friendly default for GitHub media. It accepts one or more files,
 infers the pull request for the current branch via `gh`, uploads stable URLs, and creates
 or updates one managed attachments comment. Use `--pr`, `--issue`, and `--repo` to select
 the target explicitly, or `--no-comment` to upload without changing GitHub comments.
 
+**Keys / destinations:** default put uses the `screenshots` layout. Typed destinations
+(`--destination screenshots|gh|f`, MCP `destination`) set the root; `--pr`/`--issue`
+use `gh/…`. Workspaces may restrict put/sign to those roots via
+`allowedKeyPrefixes` (see [workspaces](../../docs/workspaces.md)).
+
+**Image optimization:** by default, still images are re-encoded to WebP (long edge
+capped, high quality) before upload so GitHub embeds stay small, and **EXIF is
+stripped**. Pass `--keep-exif` / `UPLOADS_KEEP_EXIF=1` to preserve image metadata, or
+`--no-optimize` / `UPLOADS_NO_OPTIMIZE=1` to upload originals unchanged.
+
+**Frames (opt-in):** `--frame phone|browser|iphone-16-pro` composites chrome
+**before** optimize. `phone`/`browser` are procedural; `iphone-16-pro` fetches
+community art from [device-frames-media](https://github.com/jonnyjackson26/device-frames-media)
+into `~/.cache/uploads/frames` (not bundled).
+
 Config layers (first match wins): CLI flags → env vars → `--env-file` → `~/.config/buildinternet/config`. See `config.example` for keys.
 
+## MCP server
+
+`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools mirror the CLI commands one-to-one — `put`, `attach`, `list`, `delete`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`health` needs no auth).
+
+```json
+{ "command": "uploads", "args": ["--env-file", "/path/to/.env", "mcp"] }
+```
+
+Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. Claude Code: `claude mcp add uploads -- uploads --env-file /path/to/.env mcp`.
+
+For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: put/list/delete/health, same bearer tokens as the REST API — see `apps/mcp` in the repo. `uploads install` registers it with Claude Code (and installs the agent skill) in one step. Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
+
 ## Programmatic use
 
 ```ts
 import { createUploadsClient } from "@buildinternet/uploads";
 ```
 
-Agent/MCP helpers: `@buildinternet/uploads/agent` (`createUploadsWorkerFileTools` for Workers).
+Agent/MCP helpers: `@buildinternet/uploads/agent` (`createUploadsWorkerFileTools` for Workers); for local stdio MCP, use `uploads mcp` (above).
 
 ## Layout
 
@@ -44,6 +78,8 @@ Agent/MCP helpers: `@buildinternet/uploads/agent` (`createUploadsWorkerFileTools
 src/
   cli.ts            Entry + help
   commands.ts       put, list, delete, comment, …
+  commands/mcp.ts   `mcp` command entry
+  mcp/              Stdio MCP server (server.ts, tools.ts)
   client.ts         HTTP client for the API
   github.ts         PR/issue key paths + attachment comments
   embed.ts          Markdown image output

package/dist/cli.js

@@ -2,11 +2,13 @@ import { createUploadsClient } from "./client.js";
 import { resolveApiUrl, resolveConfig } from "./config.js";
 import { UploadsError } from "./errors.js";
 import { commandWorkspace, isHelpFlag, parseArgv, parseCommandArgs, UsageError, } from "./cli-args.js";
-import { runPut, runAttach, runList, runDelete, runHealth, runDoctor, runComment, } from "./commands.js";
+import { runPut, runAttach, runList, runDelete, runHealth, runDoctor, runComment, runUsage, runReconcile, runPurgeExpired, } from "./commands.js";
 import { runConfig } from "./commands/config.js";
 import { runSetup } from "./commands/setup.js";
 import { runLogin } from "./commands/login.js";
 import { runAdmin } from "./commands/admin-enrollment.js";
+import { runMcp } from "./commands/mcp.js";
+import { runInstall } from "./commands/install.js";
 const ROOT_HELP = `uploads — CLI for uploads.sh (GitHub image embeds)
 
 Usage:
@@ -37,12 +39,17 @@ Commands:
   comment             Create/update a PR/issue attachments comment (via gh)
   list                List objects
   delete <key>        Delete object
+  usage               Workspace storage / upload counters
+  reconcile           Rebuild usage ledger from storage
+  purge-expired       Delete objects past retentionDays
   setup               Inspect/configure advanced CLI settings
+  install             Install the agent skill + register the remote MCP server
   login               Exchange an enrollment code and configure credentials
   admin               Admin enrollment management
   config              Show path, init, or set shared config
   doctor              Health + auth + workspace checks
   health              API liveness (no auth)
+  mcp                 Serve MCP over stdio (tools mirror the CLI)
 
 Put/list defaults (config file or env):
   UPLOADS_DEFAULT_PREFIX, UPLOADS_DEFAULT_REPO, UPLOADS_DEFAULT_REF
@@ -55,7 +62,10 @@ Examples:
   uploads put ./shot.png --ref 42
   uploads doctor
 
-Agent/MCP: use createUploadsWorkerFileTools() from @buildinternet/uploads/agent on the Worker.
+Agent/MCP: \`uploads install\` sets up the agent skill and the hosted MCP server
+(https://agents.uploads.sh/mcp, workspace inferred from the token). Run
+\`uploads mcp\` for local stdio, or use createUploadsWorkerFileTools()
+from @buildinternet/uploads/agent on the Worker.
 `;
 function createContext(globals, requireToken, commandArgs) {
     const cmdWorkspace = commandWorkspace(parseCommandArgs(commandArgs).flags);
@@ -84,6 +94,9 @@ function exitCode(err) {
                 return 2;
             case "UNAUTHORIZED":
             case "NOT_FOUND":
+            case "KEY_POLICY":
+            case "STORAGE_QUOTA":
+            case "UPLOAD_BUDGET":
                 return 3;
             case "NETWORK":
                 return 4;
@@ -107,6 +120,17 @@ function errorOut(err, json) {
             process.stderr.write(`${msg}\n`);
         else
             process.stderr.write(`error: ${msg}\n`);
+        if (err instanceof UploadsError) {
+            if (err.code === "STORAGE_QUOTA" || err.code === "UPLOAD_BUDGET") {
+                process.stderr.write("hint: run `uploads usage` then delete objects or raise limits (`pnpm workspace:limits`)\n");
+            }
+            else if (err.code === "KEY_POLICY") {
+                process.stderr.write("hint: use a typed destination (`--destination screenshots|gh`) or an allowed prefix; operators set allowlists with `pnpm workspace:limits --allowed-prefixes`\n");
+            }
+            else if (err.status === 413 || err.message.toLowerCase().includes("too large")) {
+                process.stderr.write("hint: file exceeds workspace size policy (images vs video may differ); compress or raise --max-upload-bytes / --max-video-bytes\n");
+            }
+        }
     }
 }
 export async function runCli(argv) {
@@ -130,10 +154,17 @@ export async function runCli(argv) {
                 return runLogin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
             case "admin":
                 return runAdmin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
+            case "mcp":
+                return runMcp(cmdArgs, { globals: parsed.globals }, showHelp);
+            case "install":
+                return runInstall(cmdArgs, { globals: parsed.globals, json }, showHelp);
             case "attach":
             case "put":
             case "list":
             case "delete":
+            case "usage":
+            case "reconcile":
+            case "purge-expired":
             case "doctor":
             case "comment": {
                 const ctx = createContext(parsed.globals, !showHelp, cmdArgs);
@@ -148,6 +179,12 @@ export async function runCli(argv) {
                         return runList(ctx, cmdArgs, showHelp);
                     case "delete":
                         return runDelete(ctx, cmdArgs, showHelp);
+                    case "usage":
+                        return runUsage(ctx, cmdArgs, showHelp);
+                    case "reconcile":
+                        return runReconcile(ctx, cmdArgs, showHelp);
+                    case "purge-expired":
+                        return runPurgeExpired(ctx, cmdArgs, showHelp);
                     case "doctor":
                         return runDoctor(ctx, cmdArgs, showHelp);
                 }

package/dist/client.d.ts

@@ -43,6 +43,43 @@ export interface DeleteResult {
 export interface HealthResult {
     ok: boolean;
 }
+export interface UsageResult {
+    workspace: string;
+    bytes: number;
+    objects: number;
+    uploadsInPeriod: number;
+    periodStart: string;
+    updatedAt: string;
+    maxStorageBytes?: number;
+    storageRemainingBytes?: number;
+    maxUploadsPerPeriod?: number;
+    uploadsRemaining?: number;
+}
+export interface ReconcileResult {
+    workspace: string;
+    bytes: number;
+    objects: number;
+    previous: {
+        bytes: number;
+        objects: number;
+    };
+    changed: boolean;
+    usage: UsageResult;
+}
+export interface PurgeExpiredResult {
+    workspace: string;
+    retentionDays: number;
+    cutoff: string;
+    deleted: number;
+    freedBytes: number;
+    keys: string[];
+    keysTruncated: boolean;
+    reconcile: ReconcileResult;
+}
+export type PurgeExpiredResponse = PurgeExpiredResult | {
+    skipped: true;
+    reason: string;
+};
 export interface EnrollmentExchangeResult {
     apiUrl?: string;
     workspace: string;
@@ -67,9 +104,19 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
     put(body: Uint8Array, opts: PutOptions & {
         filename: string;
     }): Promise<PutResult>;
-    list(opts?: ListOptions): Promise<ListResult>;
+    list: (opts?: ListOptions) => Promise<ListResult>;
+    /** Follow cursors (optionally starting from one) and return every remaining item. */
+    listAll(opts?: Omit<ListOptions, "cursor"> & {
+        cursor?: string;
+    }): Promise<ListItem[]>;
     delete(key: string): Promise<DeleteResult>;
     head(key: string): Promise<HeadResult>;
     health(): Promise<HealthResult>;
+    /** Workspace storage / upload counters (+ limits when configured). */
+    usage(): Promise<UsageResult>;
+    /** Rebuild ledger bytes/objects from storage (source of truth). */
+    reconcile(): Promise<ReconcileResult>;
+    /** Delete objects past retentionDays (if set), then reconcile. */
+    purgeExpired(): Promise<PurgeExpiredResponse>;
 };
 export type UploadsClient = ReturnType<typeof createUploadsClient>;

package/dist/client.js

@@ -33,7 +33,10 @@ function encodeKeyPath(key) {
 function filesBase(config) {
     return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/files`;
 }
-function mapApiError(status, error) {
+function usageBase(config) {
+    return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/usage`;
+}
+function mapApiError(status, error, code) {
     const normalized = error.toLowerCase();
     if (status === 401 || normalized === "unauthorized") {
         return new UploadsError(error, "UNAUTHORIZED", status);
@@ -44,6 +47,16 @@ function mapApiError(status, error) {
     if (status === 400 && normalized === "invalid key") {
         return new UploadsError(error, "INVALID_KEY", status);
     }
+    if (code === "key_prefix_not_allowed" || code === "key_too_deep") {
+        return new UploadsError(error, "KEY_POLICY", status);
+    }
+    // Prefer stable body.code — bare 429 is also used for write rate limits.
+    if (status === 507 || code === "storage_quota_exceeded") {
+        return new UploadsError(error, "STORAGE_QUOTA", status);
+    }
+    if (code === "upload_budget_exceeded") {
+        return new UploadsError(error, "UPLOAD_BUDGET", status);
+    }
     return new UploadsError(error, "API_ERROR", status);
 }
 async function parseErrorResponse(res) {
@@ -51,7 +64,10 @@ async function parseErrorResponse(res) {
     const message = typeof body === "object" && body && "error" in body && typeof body.error === "string"
         ? body.error
         : res.statusText || "request failed";
-    return mapApiError(res.status, message);
+    const code = typeof body === "object" && body && "code" in body && typeof body.code === "string"
+        ? body.code
+        : undefined;
+    return mapApiError(res.status, message, code);
 }
 export function createUploadsClient(config) {
     async function request(method, path, opts) {
@@ -78,6 +94,17 @@ export function createUploadsClient(config) {
             return undefined;
         return (await res.json());
     }
+    async function list(opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.prefix)
+            params.set("prefix", opts.prefix);
+        if (opts.limit != null)
+            params.set("limit", String(opts.limit));
+        if (opts.cursor)
+            params.set("cursor", opts.cursor);
+        const qs = params.toString();
+        return request("GET", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
+    }
     return {
         async put(body, opts) {
             const key = opts.key ??
@@ -99,16 +126,17 @@ export function createUploadsClient(config) {
             }
             return { ...result, url: result.url };
         },
-        async list(opts = {}) {
-            const params = new URLSearchParams();
-            if (opts.prefix)
-                params.set("prefix", opts.prefix);
-            if (opts.limit != null)
-                params.set("limit", String(opts.limit));
-            if (opts.cursor)
-                params.set("cursor", opts.cursor);
-            const qs = params.toString();
-            return request("GET", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
+        list,
+        /** Follow cursors (optionally starting from one) and return every remaining item. */
+        async listAll(opts = {}) {
+            const items = [];
+            let cursor = opts.cursor;
+            do {
+                const page = await list({ ...opts, cursor });
+                items.push(...page.items);
+                cursor = page.cursor ?? undefined;
+            } while (cursor);
+            return items;
         },
         async delete(key) {
             return request("DELETE", `${filesBase(config)}/${encodeKeyPath(key)}`);
@@ -119,5 +147,17 @@ export function createUploadsClient(config) {
         async health() {
             return request("GET", `${config.apiUrl}/health`, { auth: false });
         },
+        /** Workspace storage / upload counters (+ limits when configured). */
+        async usage() {
+            return request("GET", usageBase(config));
+        },
+        /** Rebuild ledger bytes/objects from storage (source of truth). */
+        async reconcile() {
+            return request("POST", `${usageBase(config)}/reconcile`);
+        },
+        /** Delete objects past retentionDays (if set), then reconcile. */
+        async purgeExpired() {
+            return request("POST", `${usageBase(config)}/purge-expired`);
+        },
     };
 }

package/dist/commands/install.d.ts

@@ -0,0 +1,8 @@
+import { type GlobalFlags } from "../cli-args.js";
+import { type CommandRunner } from "../github-gh.js";
+export declare const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
+export declare function runInstall(args: string[], opts: {
+    globals: GlobalFlags;
+    json?: boolean;
+    runner?: CommandRunner;
+}, help?: boolean): Promise<number>;

package/dist/commands/install.js

@@ -0,0 +1,133 @@
+import { flagBool, flagString, parseCommandArgs, UsageError, } from "../cli-args.js";
+import { resolveConfig } from "../config.js";
+import { execRunner } from "../github-gh.js";
+export const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
+const SKILL_SOURCE = "buildinternet/uploads";
+const SKILL_NAME = "uploads-cli";
+const INSTALL_HELP = `uploads install — set up agent integrations (skill + remote MCP)
+
+Installs the uploads-cli agent skill and registers the hosted MCP server
+with Claude Code. The remote MCP endpoint infers your workspace from the
+bearer token, so only the token is needed.
+
+Usage:
+  uploads install [skill|mcp|all]     (default: all)
+
+What runs:
+  skill   npx -y skills add ${SKILL_SOURCE} --skill ${SKILL_NAME}
+  mcp     claude mcp add --transport http uploads ${DEFAULT_MCP_URL} \\
+            --header "Authorization: Bearer <token>"
+
+Options:
+  --url <endpoint>    Remote MCP endpoint (default: ${DEFAULT_MCP_URL})
+  --name <name>       MCP server name in the client (default: uploads)
+  --dry-run           Print the commands without running them
+
+Examples:
+  uploads install
+  uploads install skill
+  uploads install mcp --dry-run
+`;
+/**
+ * Masks the configured token (and any Bearer credential) in text destined
+ * for stdout/stderr/JSON — command echoes, child-process output, and error
+ * messages can all embed it.
+ */
+function redactor(token) {
+    return (text) => {
+        let out = text.replace(/Bearer \S+/g, "Bearer ***");
+        if (token)
+            out = out.split(token).join("***");
+        return out;
+    };
+}
+function runStep(run, command) {
+    try {
+        const output = run(command[0], command.slice(1)).trim();
+        return { command, ok: true, output: output || undefined };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // execFileSync's ENOENT means the binary itself is missing.
+        const hint = err.code === "ENOENT"
+            ? `${command[0]} not found on PATH — run manually: ${command.join(" ")}`
+            : message;
+        return { command, ok: false, error: hint };
+    }
+}
+export async function runInstall(args, opts, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        process.stderr.write(INSTALL_HELP);
+        return 0;
+    }
+    const target = parsed.positionals[0] ?? "all";
+    if (!["skill", "mcp", "all"].includes(target)) {
+        throw new UsageError(`unknown install target: ${target} (expected skill, mcp, or all)`);
+    }
+    const url = flagString(parsed.flags, "--url") ?? DEFAULT_MCP_URL;
+    const name = flagString(parsed.flags, "--name") ?? "uploads";
+    const dryRun = flagBool(parsed.flags, "--dry-run");
+    const run = opts.runner ?? execRunner;
+    const results = {};
+    let redact = redactor(undefined);
+    if (target === "skill" || target === "all") {
+        const command = ["npx", "-y", "skills", "add", SKILL_SOURCE, "--skill", SKILL_NAME];
+        results.skill = dryRun ? { command, ok: true, skipped: "dry-run" } : runStep(run, command);
+    }
+    if (target === "mcp" || target === "all") {
+        const config = resolveConfig({
+            apiUrl: opts.globals.apiUrl,
+            workspace: opts.globals.workspace,
+            token: opts.globals.token,
+            envFile: opts.globals.envFile,
+            requireToken: !dryRun,
+        });
+        const bearer = config.token || "<token>";
+        redact = redactor(config.token || undefined);
+        const command = [
+            "claude",
+            "mcp",
+            "add",
+            "--transport",
+            "http",
+            name,
+            url,
+            "--header",
+            `Authorization: Bearer ${bearer}`,
+        ];
+        results.mcp = dryRun ? { command, ok: true, skipped: "dry-run" } : runStep(run, command);
+    }
+    const failed = Object.values(results).some((r) => !r.ok);
+    if (opts.json) {
+        // Never echo the token in structured output — commands, child output,
+        // and error text can all embed it.
+        const redacted = Object.fromEntries(Object.entries(results).map(([key, r]) => [
+            key,
+            {
+                ...r,
+                command: r.command.map(redact),
+                output: r.output === undefined ? undefined : redact(r.output),
+                error: r.error === undefined ? undefined : redact(r.error),
+            },
+        ]));
+        process.stdout.write(JSON.stringify({ ok: !failed, steps: redacted }, null, 2) + "\n");
+        return failed ? 1 : 0;
+    }
+    for (const [step, r] of Object.entries(results)) {
+        const shown = redact(r.command.join(" "));
+        if (r.skipped)
+            process.stdout.write(`${step}: would run — ${shown}\n`);
+        else if (r.ok) {
+            process.stdout.write(`${step}: ok — ${shown}\n`);
+            if (r.output)
+                process.stdout.write(`  ${redact(r.output).split("\n").join("\n  ")}\n`);
+        }
+        else
+            process.stderr.write(`${step}: failed — ${redact(r.error ?? "")}\n`);
+    }
+    if (!failed && !dryRun) {
+        process.stderr.write("hint: restart your agent session to pick up the new skill/server\n");
+    }
+    return failed ? 1 : 0;
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,4 @@
+import { type GlobalFlags } from "../cli-args.js";
+export declare function runMcp(args: string[], opts: {
+    globals: GlobalFlags;
+}, help?: boolean): Promise<number>;

package/dist/commands/mcp.js

@@ -0,0 +1,39 @@
+import { createRequire } from "node:module";
+import { parseCommandArgs } from "../cli-args.js";
+import { createMcpServer } from "../mcp/server.js";
+import { serveStdio } from "../mcp/stdio.js";
+import { createUploadsMcpTools } from "../mcp/tools.js";
+const MCP_HELP = `uploads [globals] mcp
+
+Serve the Model Context Protocol (MCP) over stdio for agent clients. Tools
+mirror the CLI commands: put, attach, list, delete, usage, reconcile,
+purge_expired, comment, health, doctor.
+Global flags before "mcp" (--api-url, --token, --workspace, --env-file)
+configure every tool call; a per-call "workspace" argument overrides
+--workspace, like the CLI's per-command flag.
+
+Example MCP client config:
+  {
+    "command": "uploads",
+    "args": ["--env-file", "/path/.env", "mcp"]
+  }
+
+Examples:
+  uploads --env-file .env mcp
+  uploads --token up_default_… mcp
+`;
+// Same relative depth from src/commands/ and dist/commands/, so this works
+// both under vitest (src) and at runtime (dist).
+const { version } = createRequire(import.meta.url)("../../package.json");
+export async function runMcp(args, opts, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(MCP_HELP);
+        return 0;
+    }
+    const server = createMcpServer({
+        serverInfo: { name: "uploads", version },
+        tools: createUploadsMcpTools({ globals: opts.globals }),
+    });
+    await serveStdio(server);
+    return 0;
+}

package/dist/commands.d.ts

@@ -1,6 +1,11 @@
 import { type UploadsClient } from "./client.js";
+import { type CommandFlags } from "./cli-args.js";
 import { type ResolvedConfig } from "./config.js";
+import { type GhTarget } from "./github.js";
 import { type CommandRunner } from "./github-gh.js";
+import { type OptimizeImageOptions, type OptimizeImageResult } from "./optimize.js";
+import { type FrameResult } from "./frame.js";
+import type { PutDefaults } from "./config-file.js";
 export interface CliContext {
     config: ResolvedConfig;
     client: UploadsClient;
@@ -8,12 +13,70 @@ export interface CliContext {
     quiet: boolean;
     envFile?: string;
 }
+/**
+ * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
+ * neither is present. Shared by the CLI flags and the MCP tool arguments.
+ */
+export declare function makeGhTarget(pr: number | undefined, issue: number | undefined, repoArg: string | undefined, run: CommandRunner): GhTarget | undefined;
+/** Shared put/attach optimize flags + UPLOADS_NO_OPTIMIZE default. */
+export declare function optimizeOptionsFromFlags(flags: CommandFlags["flags"], defaults: PutDefaults): OptimizeImageOptions;
+export type PreparedUpload = OptimizeImageResult & {
+    frame?: Pick<FrameResult, "framed" | "frameId" | "skippedReason">;
+};
+/** Frame (optional) then optimize — shared by put/attach/MCP. */
+export declare function prepareImageForUpload(bytes: Uint8Array, filename: string, opts: {
+    frameId?: string;
+    frameUrl?: string;
+    frameFit?: "cover" | "contain";
+    optimize: OptimizeImageOptions;
+}): Promise<PreparedUpload>;
+/**
+ * List every attachment under the target's prefix and create/update the
+ * managed comment. Throws on gh failure — callers decide whether that is
+ * fatal (`comment` command) or a warning (`put --comment`).
+ */
+export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner): Promise<{
+    action: "created" | "updated" | "skipped";
+    count: number;
+}>;
 export declare function runAttach(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runPut(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runList(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runDelete(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runComment(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
+export declare function runUsage(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
+export declare function runReconcile(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
+export declare function runPurgeExpired(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runHealth(ctx: Pick<CliContext, "json"> & {
     apiUrl: string;
 }, args: string[], help?: boolean): Promise<number>;
+export interface DoctorReport {
+    ok: boolean;
+    apiUrl: string;
+    workspace: string;
+    workspaceSource: ResolvedConfig["workspaceSource"];
+    workspaceFromToken: string | undefined;
+    configPath: string;
+    configExists: boolean;
+    health: {
+        ok: boolean;
+    };
+    auth: {
+        ok: boolean;
+        error: string | undefined;
+    };
+    /** Usage snapshot when auth works (optional fields when the endpoint fails). */
+    usage?: {
+        ok: boolean;
+        bytes?: number;
+        objects?: number;
+        uploadsInPeriod?: number;
+        error?: string;
+    };
+    /** Workspace/token mismatch warning (also present in hints). */
+    warning?: string;
+    hints: string[];
+}
+/** Doctor's health + auth + workspace checks, shared by the CLI and the MCP tool. */
+export declare function buildDoctorReport(config: ResolvedConfig, client: UploadsClient): Promise<DoctorReport>;
 export declare function runDoctor(ctx: CliContext, args: string[], help?: boolean): Promise<number>;