@buildinternet/uploads 0.1.1 → 0.3.0

package/dist/mcp/server.js

@@ -0,0 +1,109 @@
+/**
+ * Minimal, dependency-free MCP (Model Context Protocol) server core.
+ *
+ * Transport is one JSON-RPC 2.0 message per line/request. This module is
+ * transport- and runtime-agnostic (usable from Workers as well as Node) —
+ * `handleLine` takes a raw message string and returns the serialized response
+ * (or undefined when no response is due), so it is directly testable. The
+ * stdio transport lives in ./stdio.ts; logs must never go to stdout.
+ */
+import { UploadsError } from "../errors.js";
+export { optPosInt, optString, usage } from "./args.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) {
+    return JSON.stringify({ jsonrpc: "2.0", id, result });
+}
+function errorResponse(id, code, message) {
+    return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
+}
+/** Tool failures become tool results (isError), never JSON-RPC errors. */
+function toolErrorText(err) {
+    if (err instanceof UploadsError)
+        return `${err.message} (${err.code})`;
+    return err instanceof Error ? err.message : String(err);
+}
+export function createMcpServer(opts) {
+    const { serverInfo, tools } = opts;
+    async function callTool(id, params) {
+        const name = params.name;
+        const tool = typeof name === "string" ? tools.find((t) => t.name === name) : undefined;
+        if (!tool)
+            return errorResponse(id, -32602, `unknown tool: ${String(name ?? "(missing)")}`);
+        const args = params.arguments ?? {};
+        if (typeof args !== "object" || args === null || Array.isArray(args)) {
+            return errorResponse(id, -32602, "tool arguments must be an object");
+        }
+        try {
+            const result = await tool.handler(args);
+            return response(id, {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+                isError: false,
+            });
+        }
+        catch (err) {
+            return response(id, {
+                content: [{ type: "text", text: toolErrorText(err) }],
+                isError: true,
+            });
+        }
+    }
+    return {
+        async handleLine(line) {
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return errorResponse(null, -32700, "Parse error");
+            }
+            // JSON-RPC batching was removed from MCP: arrays are invalid requests.
+            if (typeof msg !== "object" || msg === null || Array.isArray(msg)) {
+                return errorResponse(null, -32600, "Invalid Request");
+            }
+            const record = msg;
+            const { method, params } = record;
+            // A response from the client (has result/error, no method): ignore.
+            if (method === undefined && ("result" in record || "error" in record))
+                return undefined;
+            const id = typeof record.id === "string" || typeof record.id === "number" ? record.id : null;
+            if (typeof method !== "string")
+                return errorResponse(id, -32600, "Invalid Request");
+            if (method.startsWith("notifications/"))
+                return undefined;
+            // A request without an id is a notification — never respond.
+            if (!("id" in record))
+                return undefined;
+            const p = (typeof params === "object" && params !== null && !Array.isArray(params) ? params : {});
+            try {
+                switch (method) {
+                    case "initialize": {
+                        const requested = typeof p.protocolVersion === "string" ? p.protocolVersion : "";
+                        const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.has(requested)
+                            ? requested
+                            : LATEST_PROTOCOL_VERSION;
+                        return response(id, { protocolVersion, capabilities: { tools: {} }, serverInfo });
+                    }
+                    case "ping":
+                        return response(id, {});
+                    case "tools/list":
+                        return response(id, {
+                            tools: tools.map(({ name, description, inputSchema }) => ({
+                                name,
+                                description,
+                                inputSchema,
+                            })),
+                        });
+                    case "tools/call":
+                        return await callTool(id, p);
+                    default:
+                        return errorResponse(id, -32601, `method not found: ${method}`);
+                }
+            }
+            catch (err) {
+                return errorResponse(id, -32603, err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+}

package/dist/mcp/stdio.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "./server.js";
+/** Serve the MCP protocol on stdin/stdout; resolves when stdin ends. */
+export declare function serveStdio(server: McpServer): Promise<void>;

package/dist/mcp/stdio.js

@@ -0,0 +1,14 @@
+/** Stdio transport for the MCP server core (Node-only; the core itself is runtime-agnostic). */
+import { createInterface } from "node:readline";
+import { writeStdout } from "../io.js";
+/** Serve the MCP protocol on stdin/stdout; resolves when stdin ends. */
+export async function serveStdio(server) {
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity, terminal: false });
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        const out = await server.handleLine(line);
+        if (out !== undefined)
+            await writeStdout(out + "\n");
+    }
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,10 @@
+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";
+export declare function createUploadsMcpTools(opts: {
+    globals: GlobalFlags;
+    runner?: CommandRunner;
+    clientFactory?: (config: UploadsClientConfig) => UploadsClient;
+}): McpTool[];

package/dist/mcp/tools.js

@@ -0,0 +1,522 @@
+/**
+ * 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 { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { createUploadsClient } from "../client.js";
+import { buildDoctorReport, makeGhTarget, prepareImageForUpload, syncAttachmentsComment, } from "../commands.js";
+import { resolveFrameId } from "../frame.js";
+import { resolveConfig, resolvePutDefaults, } from "../config.js";
+import { buildMarkdown } from "../embed.js";
+import { resolvePutPrefix } from "../destinations.js";
+import { ghAttachmentKey, ghKeyPrefix } from "../github.js";
+import { rewriteKeyExtension } from "../optimize.js";
+import { execRunner, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
+import { optPosInt, optString, usage } from "./args.js";
+function optBool(args, name) {
+    const v = args[name];
+    if (v === undefined || v === null)
+        return false;
+    if (typeof v !== "boolean")
+        usage(`${name} must be a boolean`);
+    return v;
+}
+function optStringArray(args, name) {
+    const v = args[name];
+    if (v === undefined || v === null)
+        return undefined;
+    if (!Array.isArray(v) || v.some((item) => typeof item !== "string")) {
+        usage(`${name} must be an array of strings`);
+    }
+    return v;
+}
+function mcpOptimizeOptions(args, defaults) {
+    const quality = optPosInt(args, "optimizeQuality");
+    if (quality !== undefined && quality > 100)
+        usage("optimizeQuality must be 1–100");
+    return {
+        enabled: !(optBool(args, "noOptimize") || defaults.noOptimize === true),
+        maxEdge: optPosInt(args, "optimizeMaxEdge"),
+        quality,
+        keepExif: optBool(args, "keepExif") || defaults.keepExif === true,
+    };
+}
+function mcpFrameOptions(args) {
+    const raw = optString(args, "frame");
+    let frameId;
+    try {
+        frameId = resolveFrameId(raw);
+    }
+    catch (err) {
+        usage(err instanceof Error ? err.message : String(err));
+    }
+    const fitRaw = optString(args, "frameFit");
+    let frameFit;
+    if (fitRaw) {
+        if (fitRaw !== "cover" && fitRaw !== "contain") {
+            usage("frameFit must be cover or contain");
+        }
+        frameFit = fitRaw;
+    }
+    if (frameFit && !frameId)
+        usage("frameFit requires frame");
+    const frameUrl = optString(args, "frameUrl");
+    if (frameUrl && !frameId)
+        usage("frameUrl requires frame");
+    return { frameId, frameUrl, frameFit };
+}
+const frameProps = {
+    frame: {
+        type: "string",
+        description: "Optional frame before optimize: phone | browser | iphone-16-pro.",
+    },
+    frameUrl: {
+        type: "string",
+        description: "Address bar text for frame=browser.",
+    },
+    frameFit: {
+        type: "string",
+        description: "cover (default) or contain.",
+    },
+};
+/** Reads pr/issue (+ repo) into a GhTarget; undefined when neither is present. */
+function ghTargetFromArgs(args, run) {
+    return makeGhTarget(optPosInt(args, "pr"), optPosInt(args, "issue"), optString(args, "repo"), run);
+}
+const workspaceProp = {
+    type: "string",
+    description: "Override the workspace for this call (like the CLI's --workspace flag).",
+};
+/** pr/issue/repo schema properties shared by the tools that resolve a GhTarget. */
+function ghTargetProps(action) {
+    return {
+        pr: {
+            type: "number",
+            description: `${action} this pull request. Mutually exclusive with issue.`,
+        },
+        issue: {
+            type: "number",
+            description: `${action} this issue. Mutually exclusive with pr.`,
+        },
+        repo: {
+            type: "string",
+            description: "owner/name repository (default: gh/git inference).",
+        },
+    };
+}
+export function createUploadsMcpTools(opts) {
+    const { globals } = opts;
+    const run = opts.runner ?? execRunner;
+    const clientFactory = opts.clientFactory ?? createUploadsClient;
+    function clientFor(args, requireToken = true) {
+        const config = resolveConfig({
+            apiUrl: globals.apiUrl,
+            token: globals.token,
+            envFile: globals.envFile,
+            workspace: optString(args, "workspace") ?? globals.workspace,
+            requireToken,
+        });
+        return { config, client: clientFactory(config) };
+    }
+    const syncComment = async (client, target) => {
+        let comment;
+        let commentError;
+        try {
+            comment = await syncAttachmentsComment(client, target, run);
+        }
+        catch (err) {
+            // Uploads already succeeded; the comment is best-effort by design.
+            commentError = err instanceof Error ? err.message : String(err);
+        }
+        return { comment, commentError };
+    };
+    return [
+        {
+            name: "put",
+            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown (the returned `markdown` is ready to paste into a PR or issue). Pass `file` (a local path) or `contentBase64` + `filename` for in-memory content; with `pr`/`issue` the key is stable (same filename → same URL) and `comment` syncs the managed attachments comment.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file: {
+                        type: "string",
+                        description: "Path of the file to upload. Exactly one of file or contentBase64 is required.",
+                    },
+                    contentBase64: {
+                        type: "string",
+                        description: "Base64-encoded file content for in-memory uploads; requires filename.",
+                    },
+                    filename: {
+                        type: "string",
+                        description: "Filename for contentBase64 content (drives the key and content type).",
+                    },
+                    key: {
+                        type: "string",
+                        description: "Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>). Cannot be combined with pr/issue.",
+                    },
+                    destination: {
+                        type: "string",
+                        description: "Typed destination root: screenshots | gh | f. Sets the key prefix; first-class alternative to prefix. With pr/issue must be gh or omitted.",
+                    },
+                    prefix: {
+                        type: "string",
+                        description: "Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX). Cannot be combined with pr/issue.",
+                    },
+                    ...ghTargetProps("Attach to"),
+                    // put's repo doubles as the default key layout's repo segment.
+                    repo: {
+                        type: "string",
+                        description: "owner/name repo segment (default: git remote, or UPLOADS_DEFAULT_REPO).",
+                    },
+                    ref: {
+                        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)." },
+                    width: {
+                        type: "number",
+                        description: "Emit <img width=…> markdown instead of a plain image embed.",
+                    },
+                    contentType: {
+                        type: "string",
+                        description: "Override the Content-Type (ignored when optimize rewrites the body).",
+                    },
+                    noOptimize: {
+                        type: "boolean",
+                        description: "Skip client-side image optimization (default: optimize still images to WebP).",
+                    },
+                    optimizeMaxEdge: {
+                        type: "number",
+                        description: "Max long edge in pixels when optimizing (default: 2400).",
+                    },
+                    optimizeQuality: {
+                        type: "number",
+                        description: "WebP quality 1–100 when optimizing (default: 85).",
+                    },
+                    keepExif: {
+                        type: "boolean",
+                        description: "Keep EXIF/XMP/ICC when optimizing (default: strip for privacy on public embeds).",
+                    },
+                    ...frameProps,
+                    noGit: { type: "boolean", description: "Don't derive the repo segment from git." },
+                    comment: {
+                        type: "boolean",
+                        description: "With pr/issue: create or update the managed attachments comment via local gh auth (best-effort).",
+                    },
+                    workspace: workspaceProp,
+                },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const file = optString(args, "file");
+                const contentBase64 = optString(args, "contentBase64");
+                if ((file === undefined) === (contentBase64 === undefined)) {
+                    usage("exactly one of file or contentBase64 is required");
+                }
+                const filenameArg = optString(args, "filename");
+                if (contentBase64 !== undefined && !filenameArg) {
+                    usage("filename is required with contentBase64");
+                }
+                const target = ghTargetFromArgs(args, run);
+                const wantComment = optBool(args, "comment");
+                const keyArg = optString(args, "key");
+                const destArg = optString(args, "destination");
+                const prefixArg = optString(args, "prefix");
+                const refArg = optString(args, "ref");
+                if (wantComment && !target)
+                    usage("comment requires pr or issue");
+                if (target) {
+                    if (keyArg)
+                        usage("key cannot be combined with pr/issue");
+                    if (refArg)
+                        usage("ref cannot be combined with pr/issue");
+                    if (prefixArg)
+                        usage("prefix cannot be combined with pr/issue");
+                }
+                let resolvedPrefix;
+                try {
+                    resolvedPrefix = resolvePutPrefix({
+                        destination: destArg,
+                        prefix: prefixArg,
+                        key: keyArg,
+                        ghAttachment: Boolean(target),
+                    });
+                }
+                catch (err) {
+                    usage(err instanceof Error ? err.message : String(err));
+                }
+                const { client } = clientFor(args);
+                const bytes = file !== undefined
+                    ? new Uint8Array(readFileSync(file))
+                    : new Uint8Array(Buffer.from(contentBase64, "base64"));
+                const sourceName = file !== undefined ? (filenameArg ?? basename(file)) : filenameArg;
+                const defaults = resolvePutDefaults({ envFile: globals.envFile });
+                const prepared = await prepareImageForUpload(bytes, sourceName, {
+                    ...mcpFrameOptions(args),
+                    optimize: mcpOptimizeOptions(args, defaults),
+                });
+                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,
+                    prefix: resolvedPrefix ?? defaults.prefix,
+                    repo: optString(args, "repo") ?? defaults.repo,
+                    ref: refArg ?? defaults.ref,
+                    contentType: prepared.optimized ? prepared.contentType : optString(args, "contentType"),
+                    deriveRepoFromGit: !noGit,
+                });
+                const markdown = buildMarkdown(result.url, {
+                    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 (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 };
+            },
+        },
+        {
+            name: "attach",
+            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them (each upload's `markdown` is ready to paste into GitHub). With no pr/issue, targets the pull request for the current branch.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    files: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Paths of the files to upload (at least one).",
+                    },
+                    ...ghTargetProps("Attach to"),
+                    noComment: {
+                        type: "boolean",
+                        description: "Upload only; don't create/update the managed comment.",
+                    },
+                    contentType: {
+                        type: "string",
+                        description: "Override the Content-Type (applied to every file; ignored when optimize rewrites).",
+                    },
+                    noOptimize: {
+                        type: "boolean",
+                        description: "Skip client-side image optimization (default: optimize still images to WebP).",
+                    },
+                    optimizeMaxEdge: {
+                        type: "number",
+                        description: "Max long edge in pixels when optimizing (default: 2400).",
+                    },
+                    optimizeQuality: {
+                        type: "number",
+                        description: "WebP quality 1–100 when optimizing (default: 85).",
+                    },
+                    keepExif: {
+                        type: "boolean",
+                        description: "Keep EXIF/XMP/ICC when optimizing (default: strip for privacy on public embeds).",
+                    },
+                    ...frameProps,
+                    workspace: workspaceProp,
+                },
+                required: ["files"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const files = optStringArray(args, "files");
+                if (!files || files.length === 0)
+                    usage("files must be a non-empty array of paths");
+                const explicitTarget = ghTargetFromArgs(args, run);
+                const target = explicitTarget ??
+                    resolveCurrentPullRequest(resolveRepo(optString(args, "repo"), run), run);
+                const { client } = clientFor(args);
+                const contentType = optString(args, "contentType");
+                const defaults = resolvePutDefaults({ envFile: globals.envFile });
+                const frameOpts = mcpFrameOptions(args);
+                const optimizeOpts = mcpOptimizeOptions(args, defaults);
+                const uploads = [];
+                for (const file of files) {
+                    const sourceName = basename(file);
+                    const prepared = await prepareImageForUpload(new Uint8Array(readFileSync(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,
+                    });
+                    uploads.push({
+                        ...result,
+                        markdown: buildMarkdown(result.url, { alt: sourceName }),
+                        frame: prepared.frame,
+                        optimize: {
+                            optimized: prepared.optimized,
+                            skippedReason: prepared.skippedReason,
+                            originalBytes: prepared.originalBytes,
+                            outputBytes: prepared.outputBytes,
+                            filename: prepared.filename,
+                        },
+                    });
+                }
+                if (optBool(args, "noComment"))
+                    return { target, uploads };
+                const { comment, commentError } = await syncComment(client, target);
+                return { target, uploads, comment, commentError };
+            },
+        },
+        {
+            name: "list",
+            description: "List uploaded objects in the workspace, filtered by key prefix or by a PR/issue's attachments. Paginate with cursor, or set all to fetch every page.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    prefix: {
+                        type: "string",
+                        description: "Key prefix filter (default: UPLOADS_DEFAULT_PREFIX + '/'). Cannot be combined with pr/issue.",
+                    },
+                    ...ghTargetProps("List attachments for"),
+                    limit: { type: "number", description: "Page size." },
+                    cursor: { type: "string", description: "Pagination cursor from a previous call." },
+                    all: { type: "boolean", description: "Follow cursors and return every page." },
+                    workspace: workspaceProp,
+                },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const defaults = resolvePutDefaults({ envFile: globals.envFile });
+                const prefixArg = optString(args, "prefix");
+                let prefix = prefixArg ?? (defaults.prefix ? `${defaults.prefix}/` : undefined);
+                const target = ghTargetFromArgs(args, run);
+                if (target) {
+                    if (prefixArg)
+                        usage("prefix cannot be combined with pr/issue");
+                    prefix = ghKeyPrefix(target);
+                }
+                const limit = optPosInt(args, "limit");
+                const cursor = optString(args, "cursor");
+                const { client } = clientFor(args);
+                if (optBool(args, "all")) {
+                    const items = await client.listAll({ prefix, limit, cursor });
+                    return { items, cursor: null };
+                }
+                return client.list({ prefix, limit, cursor });
+            },
+        },
+        {
+            name: "delete",
+            description: "Delete an uploaded object by key. Set dryRun to preview without deleting.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "Object key to delete." },
+                    dryRun: {
+                        type: "boolean",
+                        description: "Report what would be deleted without deleting.",
+                    },
+                    workspace: workspaceProp,
+                },
+                required: ["key"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const key = optString(args, "key");
+                if (!key)
+                    usage("key is required");
+                if (optBool(args, "dryRun"))
+                    return { key, deleted: false, dryRun: true };
+                const { client } = clientFor(args);
+                return client.delete(key);
+            },
+        },
+        {
+            name: "usage",
+            description: "Workspace storage and monthly upload counters (and remaining headroom when budgets are configured). Same as `uploads usage`.",
+            inputSchema: {
+                type: "object",
+                properties: { workspace: workspaceProp },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = clientFor(args);
+                return client.usage();
+            },
+        },
+        {
+            name: "reconcile",
+            description: "Rebuild usage ledger bytes/objects from storage (source of truth). Preserves the monthly upload counter. Requires files:write. Same as `uploads reconcile`.",
+            inputSchema: {
+                type: "object",
+                properties: { workspace: workspaceProp },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = clientFor(args);
+                return client.reconcile();
+            },
+        },
+        {
+            name: "purge_expired",
+            description: "Delete objects older than the workspace retentionDays setting, then reconcile. Skips if retention is unset. Requires files:delete. Same as `uploads purge-expired`.",
+            inputSchema: {
+                type: "object",
+                properties: { workspace: workspaceProp },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = clientFor(args);
+                return client.purgeExpired();
+            },
+        },
+        {
+            name: "comment",
+            description: "Create or update the managed attachments comment on a GitHub PR or issue, listing everything uploaded for it. Uses local gh auth; edits its own prior comment in place and never touches other comments.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ...ghTargetProps("Comment on"),
+                    workspace: workspaceProp,
+                },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const target = ghTargetFromArgs(args, run);
+                if (!target)
+                    usage("comment requires pr or issue");
+                const { client } = clientFor(args);
+                const result = await syncAttachmentsComment(client, target, run);
+                return { ...target, ...result };
+            },
+        },
+        {
+            name: "health",
+            description: "Check uploads.sh API liveness. No auth or arguments required.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            async handler(args) {
+                const { config, client } = clientFor(args, false);
+                const result = await client.health();
+                return { ...result, apiUrl: config.apiUrl };
+            },
+        },
+        {
+            name: "doctor",
+            description: "Diagnose the configuration: API health, token auth, and workspace/token alignment. Returns the same report as `uploads doctor --json`, including hints.",
+            inputSchema: {
+                type: "object",
+                properties: { workspace: workspaceProp },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { config, client } = clientFor(args);
+                return buildDoctorReport(config, client);
+            },
+        },
+    ];
+}