@buildinternet/uploads 0.53.0 → 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`, `changelog`, `mcp`,
+`logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `doctor`, `health`, `changelog`, `docs`, `mcp`,
 `completion`.
 
 **Help:** bare `uploads` / `uploads help` / `--help` shows essentials; use

package/dist/cli-catalog.js

@@ -237,6 +237,11 @@ export const ROOT_COMMANDS = [
         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

@@ -17,6 +17,7 @@ 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";
@@ -243,6 +244,10 @@ export async function runCli(argv) {
                 // 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/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

@@ -5,6 +5,7 @@ export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, reso
 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

@@ -5,6 +5,7 @@ export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, reso
 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

@@ -22,6 +22,7 @@ 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

@@ -263,6 +263,20 @@ export const changelogResultSchema = objectSchema({
     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.
@@ -345,6 +359,7 @@ export const hostedOutputSchemas = {
     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 = {
@@ -379,6 +394,7 @@ export const stdioOutputSchemas = {
     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, changelog). 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

@@ -15,6 +15,7 @@ import { batchFailureMessage, mcpDestroyPublic, mcpNoAuth, mcpOAuthAny, mcpOAuth
 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)
@@ -1553,6 +1554,19 @@ 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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "mcpName": "sh.uploads/mcp",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",