@buildinternet/uploads 0.52.1 → 0.54.0

package/README.md

@@ -45,7 +45,7 @@ global `uploads` form above.
 
 Commands: `attach`, `put`, `screenshot`, `annotate`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
 `reconcile`, `purge-expired`, `setup`, `install`, `login`, `whoami` (alias `status`),
-`logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `doctor`, `health`, `mcp`,
+`logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `doctor`, `health`, `changelog`, `docs`, `mcp`,
 `completion`.
 
 **Help:** bare `uploads` / `uploads help` / `--help` shows essentials; use

package/dist/changelog.d.ts

@@ -0,0 +1,36 @@
+export declare const CHANGELOG_PAGE_URL = "https://uploads.sh/changelog";
+export declare const CHANGELOG_JSON_URL = "https://uploads.sh/changelog.json";
+export declare const CHANGELOG_XML_URL = "https://uploads.sh/changelog.xml";
+export declare const DEFAULT_CHANGELOG_LIMIT = 5;
+export declare const MAX_CHANGELOG_LIMIT = 50;
+export type ChangelogKind = "platform" | "cli";
+export type ChangelogJsonEntry = {
+    id: string;
+    kind: ChangelogKind;
+    title: string;
+    date: string;
+    url: string;
+    tags: string[];
+    summary: string;
+    body: string;
+};
+export type ChangelogDocument = {
+    url: string;
+    feed?: string;
+    entries: ChangelogJsonEntry[];
+};
+export type FetchChangelogOptions = {
+    limit?: number;
+    url?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    userAgent?: string;
+};
+/** Parse the Atom twin at /changelog.xml (fallback when JSON is not deployed yet). */
+export declare function parseChangelogAtom(xml: string): ChangelogDocument;
+export declare function parseChangelogJson(raw: unknown): ChangelogDocument;
+export declare function clampChangelogLimit(limit: number | undefined): number;
+export declare function selectChangelogEntries(doc: ChangelogDocument, limit?: number): ChangelogDocument;
+/** Human terminal output: recent titles + summaries, then a link to the page. */
+export declare function formatChangelogHuman(doc: ChangelogDocument): string;
+export declare function fetchChangelog(opts?: FetchChangelogOptions): Promise<ChangelogDocument>;

package/dist/changelog.js

@@ -0,0 +1,240 @@
+/**
+ * Fetch and format the public uploads.sh changelog for `uploads changelog`
+ * and the MCP `changelog` tool.
+ */
+import { UploadsError } from "./errors.js";
+import { packageVersion } from "./package-version.js";
+export const CHANGELOG_PAGE_URL = "https://uploads.sh/changelog";
+export const CHANGELOG_JSON_URL = "https://uploads.sh/changelog.json";
+export const CHANGELOG_XML_URL = "https://uploads.sh/changelog.xml";
+export const DEFAULT_CHANGELOG_LIMIT = 5;
+export const MAX_CHANGELOG_LIMIT = 50;
+const FETCH_TIMEOUT_MS = 8000;
+function isKind(value) {
+    return value === "platform" || value === "cli";
+}
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function asHttpUrl(value) {
+    const raw = asString(value);
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = new URL(raw);
+        if (parsed.protocol === "https:" || parsed.protocol === "http:")
+            return raw;
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function parseEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const rec = raw;
+    const id = asString(rec.id);
+    const title = asString(rec.title);
+    const date = asString(rec.date);
+    const url = asHttpUrl(rec.url);
+    const summary = asString(rec.summary);
+    if (!id || !title || !date || !url || !summary)
+        return undefined;
+    const kind = isKind(rec.kind) ? rec.kind : "platform";
+    const tags = Array.isArray(rec.tags)
+        ? rec.tags.filter((t) => typeof t === "string" && t.length > 0)
+        : [];
+    return {
+        id,
+        kind,
+        title,
+        date,
+        url,
+        tags,
+        summary,
+        body: typeof rec.body === "string" ? rec.body : "",
+    };
+}
+function decodeXml(value) {
+    return value
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&quot;", '"')
+        .replaceAll("&apos;", "'")
+        .replaceAll("&amp;", "&");
+}
+function stripHtml(html) {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function tagMatch(block, tag) {
+    const m = block.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`));
+    return m?.[1] === undefined ? undefined : decodeXml(m[1]).trim();
+}
+function attrMatch(block, tag, attr) {
+    const m = block.match(new RegExp(`<${tag}[^>]*\\s${attr}="([^"]+)"`));
+    return m?.[1] === undefined ? undefined : decodeXml(m[1]).trim();
+}
+function truncateSummary(text, maxChars = 280) {
+    if (text.length <= maxChars)
+        return text;
+    const cut = text.slice(0, maxChars - 1);
+    const atSpace = cut.lastIndexOf(" ");
+    return `${atSpace > 40 ? cut.slice(0, atSpace) : cut}…`;
+}
+/** Parse the Atom twin at /changelog.xml (fallback when JSON is not deployed yet). */
+export function parseChangelogAtom(xml) {
+    const entries = [];
+    const entryRe = /<entry>([\s\S]*?)<\/entry>/g;
+    let match;
+    while ((match = entryRe.exec(xml))) {
+        const block = match[1] ?? "";
+        const title = tagMatch(block, "title");
+        const date = tagMatch(block, "updated");
+        const url = attrMatch(block, "link", "href") ?? tagMatch(block, "id");
+        const idHref = tagMatch(block, "id") ?? url ?? "";
+        const hash = idHref.indexOf("#");
+        const id = hash >= 0 ? idHref.slice(hash + 1) : undefined;
+        const tags = [...block.matchAll(/<category\s+term="([^"]+)"/g)].map((m) => decodeXml(m[1] ?? ""));
+        const html = tagMatch(block, "content") ?? "";
+        const plain = stripHtml(html);
+        if (!title || !date || !url || !id || !plain)
+            continue;
+        const kind = tags.includes("cli") && !tags.includes("platform") ? "cli" : "platform";
+        entries.push({
+            id,
+            kind,
+            title,
+            date,
+            url,
+            tags,
+            summary: truncateSummary(plain),
+            body: plain,
+        });
+    }
+    if (entries.length === 0) {
+        throw new UploadsError("changelog Atom feed had no usable entries", "API_ERROR");
+    }
+    return { url: CHANGELOG_PAGE_URL, feed: CHANGELOG_XML_URL, entries };
+}
+export function parseChangelogJson(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new UploadsError("changelog response was not a JSON object", "API_ERROR");
+    }
+    const rec = raw;
+    if (!Array.isArray(rec.entries)) {
+        throw new UploadsError("changelog response is missing an entries array", "API_ERROR");
+    }
+    const entries = rec.entries
+        .map(parseEntry)
+        .filter((e) => e !== undefined);
+    if (rec.entries.length > 0 && entries.length === 0) {
+        throw new UploadsError("changelog response had no usable entries", "API_ERROR");
+    }
+    const feed = asHttpUrl(rec.feed);
+    return {
+        url: asHttpUrl(rec.url) ?? CHANGELOG_PAGE_URL,
+        ...(feed ? { feed } : {}),
+        entries,
+    };
+}
+export function clampChangelogLimit(limit) {
+    const n = limit ?? DEFAULT_CHANGELOG_LIMIT;
+    if (n > MAX_CHANGELOG_LIMIT)
+        return MAX_CHANGELOG_LIMIT;
+    if (n < 1)
+        return DEFAULT_CHANGELOG_LIMIT;
+    return n;
+}
+export function selectChangelogEntries(doc, limit) {
+    const n = clampChangelogLimit(limit);
+    return { ...doc, entries: doc.entries.slice(0, n) };
+}
+function formatDate(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    return d.toLocaleDateString("en-US", {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        timeZone: "UTC",
+    });
+}
+function indent(text, prefix = "  ") {
+    return text
+        .split("\n")
+        .map((line) => (line.length === 0 ? prefix.trimEnd() : `${prefix}${line}`))
+        .join("\n");
+}
+/** Human terminal output: recent titles + summaries, then a link to the page. */
+export function formatChangelogHuman(doc) {
+    const lines = ["What's new", ""];
+    if (doc.entries.length === 0) {
+        lines.push("No changelog entries.");
+    }
+    else {
+        for (const entry of doc.entries) {
+            lines.push(entry.title);
+            lines.push(`${formatDate(entry.date)}  ·  ${entry.url}`);
+            lines.push("");
+            lines.push(indent(entry.summary));
+            lines.push("");
+        }
+    }
+    lines.push(`See all updates: ${doc.url}`);
+    return `${lines.join("\n")}\n`;
+}
+async function fetchUrl(fetchImpl, url, headers, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { signal: controller.signal, headers });
+    }
+    catch (err) {
+        const aborted = err instanceof Error && err.name === "AbortError";
+        throw new UploadsError(aborted
+            ? `timed out fetching changelog (${timeoutMs}ms)`
+            : `couldn't reach changelog (${err instanceof Error ? err.message : String(err)})`, "NETWORK");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function fetchChangelog(opts = {}) {
+    const explicitUrl = opts.url;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const userAgent = opts.userAgent ?? `uploads/${packageVersion()}`;
+    const headers = { "user-agent": userAgent };
+    const jsonUrl = explicitUrl ?? CHANGELOG_JSON_URL;
+    const jsonRes = await fetchUrl(fetchImpl, jsonUrl, { ...headers, accept: "application/json" }, timeoutMs);
+    if (jsonRes.ok) {
+        try {
+            const payload = await jsonRes.json();
+            return selectChangelogEntries(parseChangelogJson(payload), opts.limit);
+        }
+        catch (err) {
+            if (explicitUrl) {
+                throw err instanceof UploadsError
+                    ? err
+                    : new UploadsError("changelog response was not valid JSON", "API_ERROR", jsonRes.status);
+            }
+        }
+    }
+    else if (explicitUrl) {
+        throw new UploadsError(`changelog returned HTTP ${jsonRes.status}; see ${CHANGELOG_PAGE_URL}`, "API_ERROR", jsonRes.status);
+    }
+    // JSON twin is new; fall back to the Atom feed that already ships.
+    const xmlRes = await fetchUrl(fetchImpl, CHANGELOG_XML_URL, { ...headers, accept: "application/atom+xml, application/xml, text/xml" }, timeoutMs);
+    if (!xmlRes.ok) {
+        throw new UploadsError(`changelog returned HTTP ${xmlRes.status}; see ${CHANGELOG_PAGE_URL}`, "API_ERROR", xmlRes.status);
+    }
+    const xml = await xmlRes.text();
+    return selectChangelogEntries(parseChangelogAtom(xml), opts.limit);
+}

package/dist/cli-catalog.js

@@ -233,6 +233,15 @@ export const ROOT_COMMANDS = [
         summary: "Update the CLI, then refresh the agent skills + MCP registration",
         essential: true,
     },
+    {
+        name: "changelog",
+        summary: "Show recent product updates (and a link to the full changelog)",
+    },
+    {
+        name: "docs",
+        summary: "Search public uploads.sh docs (or fetch one page as markdown)",
+        usage: "docs [query]",
+    },
     {
         name: "login",
         summary: "Sign in via browser (or an enrollment code) and save credentials",

package/dist/cli.js

@@ -16,6 +16,8 @@ import { runMcp } from "./commands/mcp.js";
 import { runInstall } from "./commands/install.js";
 import { runHook } from "./commands/hook.js";
 import { runUpdate } from "./commands/update.js";
+import { runChangelog } from "./commands/changelog.js";
+import { runDocs } from "./commands/docs.js";
 import { runCompletion } from "./commands/completion.js";
 import { runLogout, runWhoami } from "./commands/session.js";
 import { runTelemetry } from "./commands/telemetry.js";
@@ -238,6 +240,14 @@ export async function runCli(argv) {
             case "health":
                 code = await runHealth({ apiUrl, json }, cmdArgs, showHelp);
                 break;
+            case "changelog":
+                // Public feed — no token, independent of the API origin.
+                code = await runChangelog(cmdArgs, { json }, showHelp);
+                break;
+            case "docs":
+                // Public catalog — no token, independent of the API origin.
+                code = await runDocs(cmdArgs, { json }, showHelp);
+                break;
             case "config":
                 code = await runConfig(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
                 break;

package/dist/commands/changelog.d.ts

@@ -0,0 +1,7 @@
+import { type FetchChangelogOptions } from "../changelog.js";
+export interface RunChangelogOptions {
+    json?: boolean;
+    fetch?: FetchChangelogOptions["fetchImpl"];
+    url?: string;
+}
+export declare function runChangelog(args: string[], opts?: RunChangelogOptions, help?: boolean): Promise<number>;

package/dist/commands/changelog.js

@@ -0,0 +1,49 @@
+import { flagBool, flagInt, parseCommandArgs, UsageError } from "../cli-args.js";
+import { DEFAULT_CHANGELOG_LIMIT, MAX_CHANGELOG_LIMIT, fetchChangelog, formatChangelogHuman, } from "../changelog.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { writeJson, writeStdout } from "../io.js";
+const CHANGELOG_HELP = `uploads changelog — recent product updates
+
+Prints the latest updates from uploads.sh, then a link to the full changelog.
+
+Usage:
+  uploads changelog [options]
+
+Options:
+  --limit <n>   Number of entries to show (default: ${DEFAULT_CHANGELOG_LIMIT}, max: ${MAX_CHANGELOG_LIMIT})
+  --json        JSON on stdout (also accepts global --json)
+
+Examples:
+  uploads changelog
+  uploads changelog --limit 10
+  uploads changelog --json
+`;
+export async function runChangelog(args, opts = {}, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(CHANGELOG_HELP);
+        return 0;
+    }
+    if (parsed.positionals.length > 0) {
+        throw new UsageError(`changelog takes no arguments (got ${parsed.positionals[0]})`, {
+            example: "uploads changelog",
+        });
+    }
+    const json = Boolean(opts.json) || flagBool(parsed.flags, "--json");
+    const limit = flagInt(parsed.flags, "--limit", "--limit") ?? DEFAULT_CHANGELOG_LIMIT;
+    if (limit > MAX_CHANGELOG_LIMIT) {
+        throw new UsageError(`--limit must be ${MAX_CHANGELOG_LIMIT} or less (got ${limit})`, {
+            example: `uploads changelog --limit ${MAX_CHANGELOG_LIMIT}`,
+        });
+    }
+    const doc = await fetchChangelog({
+        limit,
+        fetchImpl: opts.fetch,
+        url: opts.url,
+    });
+    if (json)
+        await writeJson(doc);
+    else
+        await writeStdout(formatChangelogHuman(doc));
+    return 0;
+}

package/dist/commands/docs.d.ts

@@ -0,0 +1,8 @@
+import { type SearchDocsOptions } from "../docs.js";
+export interface RunDocsOptions {
+    json?: boolean;
+    fetch?: SearchDocsOptions["fetchImpl"];
+    url?: string;
+    catalog?: SearchDocsOptions["catalog"];
+}
+export declare function runDocs(args: string[], opts?: RunDocsOptions, help?: boolean): Promise<number>;

package/dist/commands/docs.js

@@ -0,0 +1,67 @@
+import { flagBool, flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+import { UploadsError } from "../errors.js";
+import { DEFAULT_DOCS_LIMIT, MAX_DOCS_LIMIT, formatDocsHuman, searchDocs, } from "../docs.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { writeJson, writeStdout } from "../io.js";
+const DOCS_HELP = `uploads docs — search public uploads.sh documentation
+
+Lists the docs catalog, searches by topic, or fetches one page as markdown.
+
+Usage:
+  uploads docs [query…] [options]
+
+Options:
+  --page <slug>  Fetch the full markdown of one page (slug, path, or URL)
+  --limit <n>    Number of search hits to show (default ${DEFAULT_DOCS_LIMIT}, max ${MAX_DOCS_LIMIT})
+  --json         JSON on stdout (also accepts global --json)
+
+Examples:
+  uploads docs
+  uploads docs stage before a PR
+  uploads docs attach
+  uploads docs --page agents
+  uploads docs --json "github app"
+`;
+export async function runDocs(args, opts = {}, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(DOCS_HELP);
+        return 0;
+    }
+    const json = Boolean(opts.json) || flagBool(parsed.flags, "--json");
+    const page = flagString(parsed.flags, "--page");
+    const limit = flagInt(parsed.flags, "--limit", "--limit");
+    if (limit !== undefined && limit > MAX_DOCS_LIMIT) {
+        throw new UsageError(`--limit must be ${MAX_DOCS_LIMIT} or less (got ${limit})`, {
+            example: `uploads docs --limit ${MAX_DOCS_LIMIT}`,
+        });
+    }
+    const query = parsed.positionals.join(" ").trim();
+    if (page && query) {
+        throw new UsageError("pass a search query or --page, not both", {
+            example: "uploads docs --page attach",
+        });
+    }
+    let doc;
+    try {
+        doc = await searchDocs({
+            query: query || undefined,
+            page: page || undefined,
+            limit,
+            fetchImpl: opts.fetch,
+            url: opts.url,
+            catalog: opts.catalog,
+        });
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.code === "USAGE") {
+            throw new UsageError(err.message, { example: "uploads docs --page attach" });
+        }
+        throw err;
+    }
+    if (json)
+        await writeJson(doc);
+    else
+        await writeStdout(formatDocsHuman(doc));
+    return 0;
+}

package/dist/docs.d.ts

@@ -0,0 +1,52 @@
+export declare const DOCS_HUB_URL = "https://uploads.sh/docs";
+export declare const DOCS_JSON_URL = "https://uploads.sh/docs.json";
+export declare const DEFAULT_DOCS_LIMIT = 5;
+export declare const MAX_DOCS_LIMIT = 50;
+export declare const DOCS_SNIPPET_MAX_CHARS = 1500;
+export declare const DOCS_PAGE_MAX_CHARS = 50000;
+export type DocsCatalogPage = {
+    page: string;
+    title: string;
+    url: string;
+    summary: string;
+    aliases: string[];
+};
+export type DocsCatalog = {
+    url: string;
+    pages: DocsCatalogPage[];
+};
+export type DocsSearchHit = {
+    title: string;
+    url: string;
+    page: string;
+    snippet: string;
+    body?: string;
+    truncated?: boolean;
+};
+export type DocsSearchDocument = {
+    url: string;
+    query?: string;
+    results: DocsSearchHit[];
+    total: number;
+};
+export type SearchDocsOptions = {
+    query?: string;
+    page?: string;
+    limit?: number;
+    url?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    userAgent?: string;
+    /** Skip the network catalog fetch (tests). */
+    catalog?: DocsCatalog;
+};
+/** Built-in catalog used when /docs.json is unreachable. */
+export declare const FALLBACK_DOCS_CATALOG: DocsCatalog;
+export declare function parseDocsCatalog(raw: unknown): DocsCatalog;
+export declare function resolveDocsPage(catalog: DocsCatalog, raw: string): DocsCatalogPage | undefined;
+export declare function rankDocsPages(catalog: DocsCatalog, query: string): DocsCatalogPage[];
+export declare function truncateDocsSnippet(text: string, maxChars?: number): string;
+/** Human terminal output for catalog/search hits. A fetched page prints its body. */
+export declare function formatDocsHuman(doc: DocsSearchDocument): string;
+export declare function loadDocsCatalog(opts?: SearchDocsOptions): Promise<DocsCatalog>;
+export declare function searchDocs(opts?: SearchDocsOptions): Promise<DocsSearchDocument>;

package/dist/docs.js

@@ -0,0 +1,439 @@
+/**
+ * Fetch and search the public uploads.sh docs catalog for `uploads docs`
+ * and the MCP `search_docs` tool.
+ */
+import { UploadsError } from "./errors.js";
+import { packageVersion } from "./package-version.js";
+export const DOCS_HUB_URL = "https://uploads.sh/docs";
+export const DOCS_JSON_URL = "https://uploads.sh/docs.json";
+export const DEFAULT_DOCS_LIMIT = 5;
+export const MAX_DOCS_LIMIT = 50;
+export const DOCS_SNIPPET_MAX_CHARS = 1500;
+export const DOCS_PAGE_MAX_CHARS = 50_000;
+const FETCH_TIMEOUT_MS = 8000;
+const SITE_ORIGIN = "https://uploads.sh";
+const STOP_WORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "at",
+    "do",
+    "for",
+    "how",
+    "i",
+    "in",
+    "is",
+    "my",
+    "of",
+    "on",
+    "or",
+    "the",
+    "to",
+    "we",
+    "your",
+]);
+/** Built-in catalog used when /docs.json is unreachable. */
+export const FALLBACK_DOCS_CATALOG = {
+    url: DOCS_HUB_URL,
+    pages: [
+        {
+            page: "docs",
+            title: "Docs",
+            url: "https://uploads.sh/docs",
+            summary: "Install the uploads CLI, attach screenshots and video to GitHub PRs, issues, and code reviews, and set up your agent.",
+            aliases: ["overview", "hub", "install"],
+        },
+        {
+            page: "attach-pull-request-images",
+            title: "Attach & share",
+            url: "https://uploads.sh/docs/attach-pull-request-images",
+            summary: "Attach screenshots and video to GitHub PRs and issues, get a public URL for any accepted file, capture a screenshot, and bake callouts or redactions onto it with the uploads CLI.",
+            aliases: [
+                "attach",
+                "stage",
+                "staging",
+                "screenshot",
+                "annotate",
+                "pr",
+                "issue",
+                "before",
+                "after",
+                "put",
+                "share",
+            ],
+        },
+        {
+            page: "galleries",
+            title: "Galleries",
+            url: "https://uploads.sh/docs/galleries",
+            summary: "Create an ordered set of media behind one public link at /g/<id>, add files with uploads put --gallery, and link the gallery to a PR or issue.",
+            aliases: ["gallery", "collection"],
+        },
+        {
+            page: "github-app",
+            title: "GitHub App",
+            url: "https://uploads.sh/docs/github-app",
+            summary: "Install the uploads-sh GitHub App so attachment comments post as the bot, private-repo PR and issue titles show on file pages, and titles stay current.",
+            aliases: ["bot", "webhook", "promote", "app", "ingest"],
+        },
+        {
+            page: "comment-config",
+            title: "Comment config",
+            url: "https://uploads.sh/docs/comment-config",
+            summary: "Reference for .uploads.yml — a repo-committed file that controls image width, inline-image caps, caption metadata, and an optional note on the managed PR/issue comment.",
+            aliases: ["uploads.yml", "comment", "yaml", "yml", "width"],
+        },
+        {
+            page: "agents",
+            title: "Set up your agent",
+            url: "https://uploads.sh/docs/agents",
+            summary: "Install the uploads agent skill and MCP server so your coding agent can attach screenshots to GitHub on its own.",
+            aliases: ["mcp", "skill", "plugin", "claude", "codex"],
+        },
+        {
+            page: "reference",
+            title: "Reference",
+            url: "https://uploads.sh/docs/reference",
+            summary: "Manage uploaded files with the uploads CLI (list, delete, usage), plus what to know about visibility, access, and stability.",
+            aliases: ["list", "delete", "usage", "visibility"],
+        },
+        {
+            page: "limits",
+            title: "Plans & limits",
+            url: "https://uploads.sh/docs/limits",
+            summary: "Storage, file size, and member limits for uploads.sh free and pro workspaces, and how they compare with GitHub's own attachment caps.",
+            aliases: ["plan", "plans", "pricing", "quota", "storage", "pro", "free"],
+        },
+        {
+            page: "byo-bucket",
+            title: "Bring your own bucket",
+            url: "https://uploads.sh/docs/byo-bucket",
+            summary: "Point a workspace at your own Cloudflare R2 or S3-compatible bucket instead of hosted storage on storage.uploads.sh.",
+            aliases: ["r2", "s3", "byo", "bucket", "bring-your-own"],
+        },
+        {
+            page: "github-screenshots",
+            title: "How to get agents to upload screenshots & video to GitHub",
+            url: "https://uploads.sh/github-screenshots",
+            summary: "One command for Claude Code, CI jobs, and scripts that captures, hosts, and posts screenshots and video to PRs and issues, before or after the PR exists.",
+            aliases: ["walkthrough", "agent-guide", "how-to"],
+        },
+        {
+            page: "changelog",
+            title: "Changelog",
+            url: "https://uploads.sh/changelog",
+            summary: "Platform updates and CLI releases, newest first.",
+            aliases: ["updates", "release", "whats-new"],
+        },
+        {
+            page: "auth",
+            title: "Auth for agents",
+            url: "https://uploads.sh/auth.md",
+            summary: "Device sign-in, workspace bearer tokens, and hosted MCP OAuth.",
+            aliases: ["login", "token", "oauth", "bearer"],
+        },
+    ],
+};
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function asHttpUrl(value) {
+    const raw = asString(value);
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = new URL(raw);
+        if (parsed.protocol === "https:" || parsed.protocol === "http:")
+            return raw;
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+}
+function parsePage(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const rec = raw;
+    const page = asString(rec.page);
+    const title = asString(rec.title);
+    const url = asHttpUrl(rec.url);
+    const summary = asString(rec.summary);
+    if (!page || !title || !url || !summary)
+        return undefined;
+    return { page, title, url, summary, aliases: asStringArray(rec.aliases) };
+}
+export function parseDocsCatalog(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new UploadsError("docs catalog was not a JSON object", "API_ERROR");
+    }
+    const rec = raw;
+    if (!Array.isArray(rec.pages)) {
+        throw new UploadsError("docs catalog is missing a pages array", "API_ERROR");
+    }
+    const pages = rec.pages.map(parsePage).filter((p) => p !== undefined);
+    if (pages.length === 0) {
+        throw new UploadsError("docs catalog had no usable pages", "API_ERROR");
+    }
+    return { url: asHttpUrl(rec.url) ?? DOCS_HUB_URL, pages };
+}
+function clampDocsLimit(limit, fallback = DEFAULT_DOCS_LIMIT) {
+    const n = limit ?? fallback;
+    if (n > MAX_DOCS_LIMIT)
+        return MAX_DOCS_LIMIT;
+    if (n < 1)
+        return fallback;
+    return n;
+}
+function tokenizeDocsQuery(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 1 && !STOP_WORDS.has(token));
+}
+function normalizeDocsKey(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/^https:\/\/uploads\.sh/i, "")
+        .replace(/^\/+/, "")
+        .replace(/\/+$/, "");
+}
+function pageKeys(page) {
+    const keys = [page.page, ...page.aliases];
+    try {
+        const path = new URL(page.url).pathname.replace(/^\/+/, "").replace(/\/+$/, "");
+        keys.push(path);
+        const leaf = path.split("/").pop();
+        if (leaf)
+            keys.push(leaf);
+        if (path.startsWith("docs/"))
+            keys.push(path.slice("docs/".length));
+    }
+    catch {
+        // Catalog URLs are validated on parse; ignore a malformed fallback entry.
+    }
+    return keys.map(normalizeDocsKey).filter(Boolean);
+}
+export function resolveDocsPage(catalog, raw) {
+    const query = normalizeDocsKey(raw);
+    if (!query)
+        return undefined;
+    const stripped = query.startsWith("docs/") ? query.slice("docs/".length) : query;
+    for (const page of catalog.pages) {
+        const keys = pageKeys(page);
+        if (keys.includes(query) || keys.includes(stripped))
+            return page;
+    }
+    return undefined;
+}
+function searchableText(page) {
+    return `${page.page} ${page.title} ${page.summary} ${page.aliases.join(" ")}`.toLowerCase();
+}
+function scoreDocsPage(page, tokens) {
+    if (tokens.length === 0)
+        return 0;
+    const text = searchableText(page);
+    let matched = 0;
+    for (const token of tokens) {
+        if (text.includes(token))
+            matched += 1;
+    }
+    if (matched === 0)
+        return 0;
+    return matched * 10 + (matched === tokens.length ? 40 : 0);
+}
+export function rankDocsPages(catalog, query) {
+    const tokens = tokenizeDocsQuery(query);
+    const needle = query.trim().toLowerCase();
+    const scored = catalog.pages
+        .map((page) => {
+        const tokenScore = tokens.length > 0 ? scoreDocsPage(page, tokens) : 0;
+        const substringScore = tokenScore === 0 && needle.length > 0 && searchableText(page).includes(needle) ? 5 : 0;
+        return { page, score: tokenScore + substringScore };
+    })
+        .filter((row) => row.score > 0)
+        .sort((a, b) => b.score - a.score || a.page.title.localeCompare(b.page.title));
+    return scored.map((row) => row.page);
+}
+export function truncateDocsSnippet(text, maxChars = DOCS_SNIPPET_MAX_CHARS) {
+    const trimmed = text.trim();
+    if (trimmed.length <= maxChars)
+        return trimmed;
+    const cut = trimmed.slice(0, maxChars - 1);
+    const atSpace = cut.lastIndexOf(" ");
+    return `${atSpace > 40 ? cut.slice(0, atSpace) : cut}…`;
+}
+function hitFromPage(page, body) {
+    if (body === undefined) {
+        return {
+            title: page.title,
+            url: page.url,
+            page: page.page,
+            snippet: page.summary,
+        };
+    }
+    const clipped = body.length > DOCS_PAGE_MAX_CHARS ? body.slice(0, DOCS_PAGE_MAX_CHARS) : body;
+    const snippet = truncateDocsSnippet(clipped);
+    return {
+        title: page.title,
+        url: page.url,
+        page: page.page,
+        snippet,
+        body: clipped,
+        ...(snippet.length < clipped.trim().length || body.length > DOCS_PAGE_MAX_CHARS
+            ? { truncated: true }
+            : {}),
+    };
+}
+function indent(text, prefix = "  ") {
+    return text
+        .split("\n")
+        .map((line) => (line.length === 0 ? prefix.trimEnd() : `${prefix}${line}`))
+        .join("\n");
+}
+/** Human terminal output for catalog/search hits. A fetched page prints its body. */
+export function formatDocsHuman(doc) {
+    const lines = [];
+    const only = doc.results.length === 1 ? doc.results[0] : undefined;
+    if (only?.body) {
+        lines.push(only.title);
+        lines.push(only.url);
+        lines.push("");
+        lines.push(only.body.trimEnd());
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push("Docs", "");
+    if (doc.results.length === 0) {
+        lines.push("No matching docs.");
+    }
+    else {
+        for (const hit of doc.results) {
+            lines.push(hit.title);
+            lines.push(hit.url);
+            lines.push("");
+            lines.push(indent(hit.snippet));
+            lines.push("");
+        }
+    }
+    lines.push(`See all docs: ${doc.url}`);
+    return `${lines.join("\n")}\n`;
+}
+function isUploadsDocsUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.origin === SITE_ORIGIN;
+    }
+    catch {
+        return false;
+    }
+}
+async function fetchUrl(fetchImpl, url, headers, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { signal: controller.signal, headers });
+    }
+    catch (err) {
+        const aborted = err instanceof Error && err.name === "AbortError";
+        throw new UploadsError(aborted
+            ? `timed out fetching docs (${timeoutMs}ms)`
+            : `couldn't reach docs (${err instanceof Error ? err.message : String(err)})`, "NETWORK");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function loadDocsCatalog(opts = {}) {
+    if (opts.catalog)
+        return opts.catalog;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const userAgent = opts.userAgent ?? `uploads/${packageVersion()}`;
+    const jsonUrl = opts.url ?? DOCS_JSON_URL;
+    try {
+        const res = await fetchUrl(fetchImpl, jsonUrl, { "user-agent": userAgent, accept: "application/json" }, timeoutMs);
+        if (res.ok) {
+            try {
+                const payload = await res.json();
+                return parseDocsCatalog(payload);
+            }
+            catch (err) {
+                if (opts.url) {
+                    throw err instanceof UploadsError
+                        ? err
+                        : new UploadsError("docs catalog was not valid JSON", "API_ERROR", res.status);
+                }
+            }
+        }
+        else if (opts.url) {
+            throw new UploadsError(`docs catalog returned HTTP ${res.status}; see ${DOCS_HUB_URL}`, "API_ERROR", res.status);
+        }
+    }
+    catch (err) {
+        if (opts.url)
+            throw err;
+    }
+    return FALLBACK_DOCS_CATALOG;
+}
+async function fetchPageMarkdown(page, opts) {
+    if (!isUploadsDocsUrl(page.url)) {
+        throw new UploadsError(`refusing to fetch docs outside ${SITE_ORIGIN}`, "USAGE");
+    }
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const userAgent = opts.userAgent ?? `uploads/${packageVersion()}`;
+    const res = await fetchUrl(fetchImpl, page.url, {
+        "user-agent": userAgent,
+        accept: "text/markdown, text/plain;q=0.9",
+    }, timeoutMs);
+    if (!res.ok) {
+        throw new UploadsError(`docs page returned HTTP ${res.status}; see ${page.url}`, "API_ERROR", res.status);
+    }
+    const body = await res.text();
+    return hitFromPage(page, body);
+}
+export async function searchDocs(opts = {}) {
+    const catalog = await loadDocsCatalog(opts);
+    const pageArg = opts.page?.trim();
+    const query = opts.query?.trim();
+    if (pageArg) {
+        const page = resolveDocsPage(catalog, pageArg);
+        if (!page) {
+            throw new UploadsError(`unknown docs page: ${pageArg}`, "USAGE");
+        }
+        const hit = await fetchPageMarkdown(page, opts);
+        return {
+            url: catalog.url,
+            query: pageArg,
+            results: [hit],
+            total: 1,
+        };
+    }
+    if (query) {
+        const exact = resolveDocsPage(catalog, query);
+        if (exact && !/\s/.test(query)) {
+            const hit = await fetchPageMarkdown(exact, opts);
+            return { url: catalog.url, query, results: [hit], total: 1 };
+        }
+        const ranked = rankDocsPages(catalog, query);
+        const sliced = ranked.slice(0, clampDocsLimit(opts.limit));
+        return {
+            url: catalog.url,
+            query,
+            results: sliced.map((page) => hitFromPage(page)),
+            total: ranked.length,
+        };
+    }
+    const sliced = opts.limit === undefined ? catalog.pages : catalog.pages.slice(0, clampDocsLimit(opts.limit));
+    return {
+        url: catalog.url,
+        results: sliced.map((page) => hitFromPage(page)),
+        total: catalog.pages.length,
+    };
+}

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, type BuiltinDestinationId, } from "./destinations.js";
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, type UploadsClientConfig, type ResolvedConfig, type WorkspaceSource, type ConfigValueSource, type ConfigSources, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config.js";
 export { UploadsError, type UploadsErrorCode } from "./errors.js";
+export { CHANGELOG_JSON_URL, CHANGELOG_PAGE_URL, CHANGELOG_XML_URL, DEFAULT_CHANGELOG_LIMIT, MAX_CHANGELOG_LIMIT, fetchChangelog, formatChangelogHuman, parseChangelogAtom, parseChangelogJson, selectChangelogEntries, type ChangelogDocument, type ChangelogJsonEntry, type FetchChangelogOptions, } from "./changelog.js";
+export { DEFAULT_DOCS_LIMIT, DOCS_HUB_URL, DOCS_JSON_URL, MAX_DOCS_LIMIT, formatDocsHuman, searchDocs, type DocsCatalog, type DocsSearchDocument, type SearchDocsOptions, } from "./docs.js";
 export { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, resolveUploadFilename, FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES, FETCH_UPLOAD_SOURCE_MAX_REDIRECTS, FETCH_UPLOAD_SOURCE_TIMEOUT_MS, } from "./fetch-upload-source.js";
 export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, type ResolveGhPrefixOptions, type ResolveGhPrefixResult, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";

package/dist/index.js

@@ -4,6 +4,8 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, } from "./destinations.js";
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, } from "./config.js";
 export { UploadsError } from "./errors.js";
+export { CHANGELOG_JSON_URL, CHANGELOG_PAGE_URL, CHANGELOG_XML_URL, DEFAULT_CHANGELOG_LIMIT, MAX_CHANGELOG_LIMIT, fetchChangelog, formatChangelogHuman, parseChangelogAtom, parseChangelogJson, selectChangelogEntries, } from "./changelog.js";
+export { DEFAULT_DOCS_LIMIT, DOCS_HUB_URL, DOCS_JSON_URL, MAX_DOCS_LIMIT, formatDocsHuman, searchDocs, } from "./docs.js";
 export { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, resolveUploadFilename, FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES, FETCH_UPLOAD_SOURCE_MAX_REDIRECTS, FETCH_UPLOAD_SOURCE_TIMEOUT_MS, } from "./fetch-upload-source.js";
 export { createUploadsClient, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";

package/dist/mcp/docs-tool.d.ts

@@ -0,0 +1,4 @@
+import { type ToolArgs } from "./args.js";
+export declare const SEARCH_DOCS_DESCRIPTION = "Search the public uploads.sh documentation. Use this to answer questions about uploads.sh product workflows, including: attaching screenshots and video to GitHub PRs and issues; staging files before a PR exists; galleries; the GitHub App; comment config (.uploads.yml); hosted MCP and agent setup; screenshot capture and annotate; plans and limits; bring-your-own bucket. Same as `uploads docs`. Returns titles, URLs, and snippets. Pass `page` to fetch the full markdown of one page (slug, path, or URL). Omit `query` to list the catalog.";
+export declare const SEARCH_DOCS_INPUT_SCHEMA: Record<string, unknown>;
+export declare function runSearchDocsTool(args: ToolArgs): Promise<import("../docs.js").DocsSearchDocument>;

package/dist/mcp/docs-tool.js

@@ -0,0 +1,35 @@
+/**
+ * Shared MCP `search_docs` surface for stdio and hosted servers.
+ */
+import { DEFAULT_DOCS_LIMIT, MAX_DOCS_LIMIT, searchDocs } from "../docs.js";
+import { optPosInt, optString, usage } from "./args.js";
+export const SEARCH_DOCS_DESCRIPTION = "Search the public uploads.sh documentation. Use this to answer questions about uploads.sh product workflows, including: attaching screenshots and video to GitHub PRs and issues; staging files before a PR exists; galleries; the GitHub App; comment config (.uploads.yml); hosted MCP and agent setup; screenshot capture and annotate; plans and limits; bring-your-own bucket. Same as `uploads docs`. Returns titles, URLs, and snippets. Pass `page` to fetch the full markdown of one page (slug, path, or URL). Omit `query` to list the catalog.";
+export const SEARCH_DOCS_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: "Search query (e.g. 'stage before a PR'). A single slug like 'attach' fetches that page.",
+        },
+        page: {
+            type: "string",
+            description: "Fetch one page as markdown. Accepts a slug (`attach`), path (`/docs/agents`), or https://uploads.sh URL.",
+        },
+        limit: {
+            type: "number",
+            description: `How many search hits to return (default ${DEFAULT_DOCS_LIMIT}, max ${MAX_DOCS_LIMIT}). Ignored when fetching one page.`,
+        },
+    },
+    additionalProperties: false,
+};
+export async function runSearchDocsTool(args) {
+    const query = optString(args, "query");
+    const page = optString(args, "page");
+    if (query && page)
+        usage("pass query or page, not both");
+    const limit = optPosInt(args, "limit");
+    if (limit !== undefined && limit > MAX_DOCS_LIMIT) {
+        usage(`limit must be ${MAX_DOCS_LIMIT} or less`);
+    }
+    return searchDocs({ query, page, limit });
+}

package/dist/mcp/output-schemas.d.ts

@@ -21,6 +21,8 @@ export declare const usageResultSchema: JsonSchema;
 export declare const reconcileResultSchema: JsonSchema;
 export declare const purgeExpiredResultSchema: JsonSchema;
 export declare const whoamiResultSchema: JsonSchema;
+export declare const changelogResultSchema: JsonSchema;
+export declare const searchDocsResultSchema: JsonSchema;
 export declare const promoteToolResultSchema: JsonSchema;
 export declare const galleryResultSchema: JsonSchema;
 export declare const galleryFindResultSchema: JsonSchema;

package/dist/mcp/output-schemas.js

@@ -248,6 +248,35 @@ export const whoamiResultSchema = objectSchema({
     signedIn: { type: "boolean" },
     apiUrl: { type: "string" },
 }, ["ok", "workspace"]);
+const changelogEntrySchema = objectSchema({
+    id: { type: "string" },
+    kind: { type: "string", enum: ["platform", "cli"] },
+    title: { type: "string" },
+    date: { type: "string" },
+    url: { type: "string" },
+    tags: { type: "array", items: { type: "string" } },
+    summary: { type: "string" },
+    body: { type: "string" },
+}, ["id", "kind", "title", "date", "url", "tags", "summary", "body"]);
+export const changelogResultSchema = objectSchema({
+    url: { type: "string" },
+    feed: { type: "string" },
+    entries: { type: "array", items: changelogEntrySchema },
+}, ["url", "entries"]);
+const docsSearchHitSchema = objectSchema({
+    title: { type: "string" },
+    url: { type: "string" },
+    page: { type: "string" },
+    snippet: { type: "string" },
+    body: { type: "string" },
+    truncated: { type: "boolean" },
+}, ["title", "url", "page", "snippet"]);
+export const searchDocsResultSchema = objectSchema({
+    url: { type: "string" },
+    query: { type: "string" },
+    results: { type: "array", items: docsSearchHitSchema },
+    total: { type: "number" },
+}, ["url", "results", "total"]);
 export const promoteToolResultSchema = objectSchema({
     // `promotion` is optional (issue #702): a `keys`-only call (no `branch`)
     // never runs the branch sweep, so there's nothing to report under it.
@@ -329,6 +358,8 @@ export const hostedOutputSchemas = {
     reconcile: reconcileResultSchema,
     purge_expired: purgeExpiredResultSchema,
     whoami: whoamiResultSchema,
+    changelog: changelogResultSchema,
+    search_docs: searchDocsResultSchema,
 };
 /** Shared-shape stdio tools. Hosted-only tools (`promote`, `repo_link_status`) omitted. */
 export const stdioOutputSchemas = {
@@ -362,6 +393,8 @@ export const stdioOutputSchemas = {
     reconcile: reconcileResultSchema,
     purge_expired: purgeExpiredResultSchema,
     whoami: whoamiResultSchema,
+    changelog: changelogResultSchema,
+    search_docs: searchDocsResultSchema,
     report: objectSchema({
         ok: { type: "boolean" },
         id: { type: "string" },

package/dist/mcp/server.d.ts

@@ -20,6 +20,7 @@
 import { McpServer, type Implementation, type jsonSchemaValidator } from "@modelcontextprotocol/server";
 export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, METADATA_PATH_CUE, MCP_EXAMPLE_PNG_BASE64, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
+export { SEARCH_DOCS_DESCRIPTION, SEARCH_DOCS_INPUT_SCHEMA, runSearchDocsTool, } from "./docs-tool.js";
 export { mapBounded } from "../async.js";
 export { McpServer, type jsonSchemaValidator };
 export { commentResultSchema, deleteResultSchema, findFilesResultSchema, galleryFindResultSchema, galleryResultSchema, hostedOutputSchemas, listResultSchema, metadataFacetsResultSchema, metadataResultSchema, promoteToolResultSchema, purgeExpiredResultSchema, putResultSchema, reconcileResultSchema, repoLinkStatusResultSchema, stdioOutputSchemas, usageResultSchema, withOutputSchemas, } from "./output-schemas.js";

package/dist/mcp/server.js

@@ -23,6 +23,7 @@ import { errorCodeFromUnknown, recordEvent } from "../telemetry.js";
 import { ToolBatchError } from "./batch-error.js";
 export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, METADATA_PATH_CUE, MCP_EXAMPLE_PNG_BASE64, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
+export { SEARCH_DOCS_DESCRIPTION, SEARCH_DOCS_INPUT_SCHEMA, runSearchDocsTool, } from "./docs-tool.js";
 export { mapBounded } from "../async.js";
 export { McpServer };
 export { commentResultSchema, deleteResultSchema, findFilesResultSchema, galleryFindResultSchema, galleryResultSchema, hostedOutputSchemas, listResultSchema, metadataFacetsResultSchema, metadataResultSchema, promoteToolResultSchema, purgeExpiredResultSchema, putResultSchema, reconcileResultSchema, repoLinkStatusResultSchema, stdioOutputSchemas, usageResultSchema, withOutputSchemas, } from "./output-schemas.js";

package/dist/mcp/tools.d.ts

@@ -1,6 +1,7 @@
 /**
  * MCP tool set mirroring the CLI commands (put, attach, list, delete,
- * usage, reconcile, purge_expired, comment, whoami, doctor). Config is
+ * usage, reconcile, purge_expired, comment, whoami, doctor, changelog,
+ * search_docs). 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.

package/dist/mcp/tools.js

@@ -14,6 +14,8 @@ import { appProp, canonicalMetaFromArgs, METADATA_PATH_CUE, metadataArgWithCanon
 import { batchFailureMessage, mcpDestroyPublic, mcpNoAuth, mcpOAuthAny, mcpOAuthDelete, mcpOAuthRead, mcpOAuthWrite, mcpRead, mcpWriteInternal, mcpWritePublic, stdioOutputSchemas, withOutputSchemas, ToolBatchError, } from "./server.js";
 import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
 import { resolveApiUrl } from "../config.js";
+import { DEFAULT_CHANGELOG_LIMIT, MAX_CHANGELOG_LIMIT, fetchChangelog } from "../changelog.js";
+import { SEARCH_DOCS_DESCRIPTION, SEARCH_DOCS_INPUT_SCHEMA, runSearchDocsTool, } from "./docs-tool.js";
 function mcpOptimizeOptions(args, defaults) {
     const quality = optPosInt(args, "optimizeQuality");
     if (quality !== undefined && quality > 100)
@@ -1552,6 +1554,46 @@ export function createUploadsMcpTools(opts) {
                 return { ...target, ...result };
             },
         },
+        {
+            name: "search_docs",
+            title: "Search uploads.sh docs",
+            annotations: {
+                readOnlyHint: true,
+                destructiveHint: false,
+                openWorldHint: true,
+            },
+            securitySchemes: mcpNoAuth,
+            description: SEARCH_DOCS_DESCRIPTION,
+            inputSchema: SEARCH_DOCS_INPUT_SCHEMA,
+            handler: runSearchDocsTool,
+        },
+        {
+            name: "changelog",
+            title: "Product changelog",
+            annotations: {
+                readOnlyHint: true,
+                destructiveHint: false,
+                openWorldHint: true,
+            },
+            securitySchemes: mcpNoAuth,
+            description: "Read recent uploads.sh product updates (platform and CLI). Returns the latest entries with titles, dates, summaries, and a link to the full changelog at https://uploads.sh/changelog. Same as `uploads changelog`. Use this to discover new features before recommending uploads.sh workflows.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    limit: {
+                        type: "number",
+                        description: `How many entries to return (default ${DEFAULT_CHANGELOG_LIMIT}, max ${MAX_CHANGELOG_LIMIT}).`,
+                    },
+                },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const limit = optPosInt(args, "limit") ?? DEFAULT_CHANGELOG_LIMIT;
+                if (limit > MAX_CHANGELOG_LIMIT)
+                    usage(`limit must be ${MAX_CHANGELOG_LIMIT} or less`);
+                return fetchChangelog({ limit });
+            },
+        },
         {
             name: "whoami",
             title: "Who am I",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.52.1",
+  "version": "0.54.0",
   "mcpName": "sh.uploads/mcp",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
@@ -39,7 +39,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "files-sdk": "^2.2.4"
+    "files-sdk": "^2.3.1"
   },
   "peerDependenciesMeta": {
     "files-sdk": {
@@ -49,7 +49,7 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "ai": "^6.0.0",
-    "files-sdk": "^2.2.5",
+    "files-sdk": "^2.3.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },