@buildinternet/uploads 0.35.0 → 0.36.0

package/dist/commands/mcp.js

@@ -1,7 +1,8 @@
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/server/validators/ajv";
 import { parseCommandArgs } from "../cli-args.js";
 import { resolveApiUrl } from "../config.js";
 import { createMcpServer } from "../mcp/server.js";
-import { serveStdio } from "../mcp/stdio.js";
 import { createUploadsMcpTools } from "../mcp/tools.js";
 import { packageVersion } from "../package-version.js";
 import { writeCommandHelp } from "../cli-style.js";
@@ -29,11 +30,23 @@ export async function runMcp(args, opts, help = false) {
         writeCommandHelp(MCP_HELP);
         return 0;
     }
-    const server = createMcpServer({
+    // Ajv is the right provider here and only here: it compiles schemas at
+    // runtime, which Node allows and workerd does not (apps/mcp passes the
+    // `@cfworker/json-schema` provider instead).
+    const validator = new AjvJsonSchemaValidator();
+    const handle = serveStdio(() => createMcpServer({
         serverInfo: { name: "uploads", version: packageVersion() },
         tools: createUploadsMcpTools({ globals: opts.globals }),
         apiUrl: resolveApiUrl(opts.globals),
+        validator,
+    }));
+    // `serveStdio` hands back only a teardown handle, so the command owns the
+    // wait: serving ends when the client closes our stdin, which is what the
+    // previous readline loop returned on.
+    await new Promise((resolve) => {
+        process.stdin.once("end", resolve);
+        process.stdin.once("close", resolve);
     });
-    await serveStdio(server);
+    await handle.close();
     return 0;
 }

package/dist/github-gh.d.ts

@@ -74,6 +74,13 @@ export declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: Co
  * deleted best-effort via `gh api -X DELETE`; a failed delete is swallowed
  * and never fails the caller's command, and the next sync retries anyway.
  *
+ * A create additionally re-hunts once it has written (issue #553, mirroring
+ * the bot path): find-or-create is not atomic, so a concurrent writer can
+ * create its own comment in the same window. Both writers independently agree
+ * the OLDEST marker comment wins, fold their body into it and delete the rest
+ * — including their own create — so the race converges instead of leaving a
+ * stale orphan behind for a PR that never syncs again.
+ *
  * On why this duplicates the bot path rather than deferring to it: the gh
  * fallback is a supported path, not a stopgap, so it is held at behavioral
  * parity deliberately. This file already reimplements the hunt, the legacy

package/dist/github-gh.js

@@ -266,6 +266,13 @@ function findManagedComment(target, run, marker) {
  * deleted best-effort via `gh api -X DELETE`; a failed delete is swallowed
  * and never fails the caller's command, and the next sync retries anyway.
  *
+ * A create additionally re-hunts once it has written (issue #553, mirroring
+ * the bot path): find-or-create is not atomic, so a concurrent writer can
+ * create its own comment in the same window. Both writers independently agree
+ * the OLDEST marker comment wins, fold their body into it and delete the rest
+ * — including their own create — so the race converges instead of leaving a
+ * stale orphan behind for a PR that never syncs again.
+ *
  * On why this duplicates the bot path rather than deferring to it: the gh
  * fallback is a supported path, not a stopgap, so it is held at behavioral
  * parity deliberately. This file already reimplements the hunt, the legacy
@@ -281,26 +288,9 @@ function findManagedComment(target, run, marker) {
 export function upsertAttachmentsComment(target, body, run = execRunner, marker = ATTACHMENTS_MARKER, opts = {}) {
     const createIfMissing = opts.createIfMissing ?? true;
     const { comment: existing, extras } = findManagedComment(target, run, marker);
-    const deleteExtras = () => {
-        for (const extra of extras ?? []) {
-            try {
-                run("gh", ["api", `repos/${target.repo}/issues/comments/${extra.id}`, "-X", "DELETE"]);
-            }
-            catch {
-                // Best effort only — a failed delete must never fail the caller's command.
-            }
-        }
-    };
     if (existing) {
-        run("gh", [
-            "api",
-            `repos/${target.repo}/issues/comments/${existing.id}`,
-            "-X",
-            "PATCH",
-            "-F",
-            "body=@-",
-        ], body);
-        deleteExtras();
+        patchComment(target, run, existing.id, body);
+        deleteComments(target, run, extras);
         return { action: "updated" };
     }
     // Patch-only (createIfMissing false, i.e. an empty body) with no existing
@@ -308,7 +298,65 @@ export function upsertAttachmentsComment(target, body, run = execRunner, marker
     if (!createIfMissing)
         return { action: "skipped" };
     // No existing marker hit means `extras` is necessarily empty here (see
-    // `findManagedComment`) — nothing to delete after a create.
-    run("gh", ["api", `repos/${target.repo}/issues/${target.num}/comments`, "-F", "body=@-"], body);
-    return { action: "created" };
+    // `findManagedComment`) — nothing to delete before the create.
+    const created = run("gh", ["api", `repos/${target.repo}/issues/${target.num}/comments`, "-F", "body=@-"], body);
+    return reconcileAfterCreate(target, body, run, marker, created) ?? { action: "created" };
+}
+/**
+ * Re-hunt right after a create and collapse whatever a concurrent writer left
+ * behind (issue #553). Returns `{ action: "updated" }` when this run lost the
+ * race — its body has been folded into the older winning comment and its own
+ * create deleted — or null when nothing needed folding, including every
+ * failure: a verification problem must never fail a successful create.
+ *
+ * The winner is patched BEFORE any delete, so a failed fold leaves both
+ * comments (the next sync's hunt retries) rather than deleting the one that
+ * carries the current body.
+ */
+function reconcileAfterCreate(target, body, run, marker, createdRaw) {
+    let createdId;
+    try {
+        createdId = JSON.parse(createdRaw).id;
+    }
+    catch {
+        // `gh` printed something unparseable — fall through to the hunt, which
+        // identifies the winner on its own.
+    }
+    try {
+        const { comment: winner, extras } = findManagedComment(target, run, marker);
+        // `extras` is undefined in legacy mode, where a second hit may belong to
+        // another workspace — the adopt-only contract holds here too.
+        if (!winner || !extras?.length)
+            return null;
+        if (winner.id === createdId) {
+            // Ours is the oldest and already carries the body we just wrote — only
+            // the other writer's duplicate needs to go.
+            deleteComments(target, run, extras);
+            return null;
+        }
+        patchComment(target, run, winner.id, body);
+        deleteComments(target, run, extras);
+        return { action: "updated" };
+    }
+    catch {
+        // A failed listing or fold leaves the freshly created comment in place —
+        // correct content, one duplicate, healed by the next sync's hunt.
+        return null;
+    }
+}
+/** PATCH one comment's body via stdin, so the body is never shell-interpolated. */
+function patchComment(target, run, id, body) {
+    run("gh", ["api", `repos/${target.repo}/issues/comments/${id}`, "-X", "PATCH", "-F", "body=@-"], body);
+}
+/** Best-effort delete: a failed delete must never fail the caller's command,
+ * and the next sync's hunt retries anyway. */
+function deleteComments(target, run, comments) {
+    for (const c of comments ?? []) {
+        try {
+            run("gh", ["api", `repos/${target.repo}/issues/comments/${c.id}`, "-X", "DELETE"]);
+        }
+        catch {
+            // Best effort only.
+        }
+    }
 }

package/dist/mcp/server.d.ts

@@ -1,6 +1,27 @@
+/**
+ * MCP (Model Context Protocol) server core, built on the v2 TypeScript SDK
+ * (`@modelcontextprotocol/server`), which speaks spec `2026-07-28` and the
+ * 2025-era revisions side by side.
+ *
+ * Tools stay declarative: callers pass `McpTool[]` with hand-written JSON
+ * Schema and this module registers them with the SDK. That keeps the two tool
+ * sets (./tools.ts and apps/mcp/src/tools.ts) free of SDK imports and confines
+ * the dependency to this file.
+ *
+ * Runtime-agnostic, so the JSON Schema validator is injected rather than
+ * chosen here: the SDK bundles no provider in its root entry, and the two
+ * available ones are not interchangeable — Ajv compiles schemas at runtime and
+ * workerd rejects that, so Workers callers must pass the `@cfworker/json-schema`
+ * provider. See `@modelcontextprotocol/server/validators/{ajv,cf-worker}`.
+ *
+ * The stdio transport comes from `@modelcontextprotocol/server/stdio`; logs
+ * must never go to stdout.
+ */
+import { McpServer, type jsonSchemaValidator } from "@modelcontextprotocol/server";
 export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 export { mapBounded } from "../async.js";
+export { McpServer, type jsonSchemaValidator };
 export interface McpTool {
     name: string;
     description: string;
@@ -8,10 +29,6 @@ export interface McpTool {
     inputSchema: Record<string, unknown>;
     handler: (args: Record<string, unknown>) => Promise<unknown>;
 }
-export interface McpServer {
-    /** Handle one JSON-RPC line. Undefined for notifications / client responses. */
-    handleLine(line: string): Promise<string | undefined>;
-}
 export declare function createMcpServer(opts: {
     serverInfo: {
         name: string;
@@ -20,4 +37,9 @@ export declare function createMcpServer(opts: {
     tools: McpTool[];
     /** API base for telemetry (honors uploads --api-url). */
     apiUrl?: string;
+    /**
+     * Runtime's JSON Schema validator. Node callers pass the Ajv provider;
+     * Workers callers must pass the `@cfworker/json-schema` one.
+     */
+    validator: jsonSchemaValidator;
 }): McpServer;

package/dist/mcp/server.js

@@ -1,58 +1,62 @@
 /**
- * Minimal, dependency-free MCP (Model Context Protocol) server core.
+ * MCP (Model Context Protocol) server core, built on the v2 TypeScript SDK
+ * (`@modelcontextprotocol/server`), which speaks spec `2026-07-28` and the
+ * 2025-era revisions side by side.
  *
- * 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.
+ * Tools stay declarative: callers pass `McpTool[]` with hand-written JSON
+ * Schema and this module registers them with the SDK. That keeps the two tool
+ * sets (./tools.ts and apps/mcp/src/tools.ts) free of SDK imports and confines
+ * the dependency to this file.
+ *
+ * Runtime-agnostic, so the JSON Schema validator is injected rather than
+ * chosen here: the SDK bundles no provider in its root entry, and the two
+ * available ones are not interchangeable — Ajv compiles schemas at runtime and
+ * workerd rejects that, so Workers callers must pass the `@cfworker/json-schema`
+ * provider. See `@modelcontextprotocol/server/validators/{ajv,cf-worker}`.
+ *
+ * The stdio transport comes from `@modelcontextprotocol/server/stdio`; logs
+ * must never go to stdout.
  */
+import { fromJsonSchema, McpServer, } from "@modelcontextprotocol/server";
 import { UploadsError } from "../errors.js";
 import { errorCodeFromUnknown, recordEvent } from "../telemetry.js";
 import { ToolBatchError } from "./batch-error.js";
 export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 export { mapBounded } from "../async.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 } });
-}
+export { McpServer };
+/**
+ * The tool catalog is fixed for the lifetime of a deploy, so a generous
+ * freshness hint is honest. `private` rather than `public` because the list is
+ * behind auth and, on the hosted worker, filtered by the caller's token
+ * scopes — a shared intermediary must never serve one caller's tool list to
+ * another.
+ */
+const TOOLS_LIST_CACHE_HINT = { ttlMs: 3_600_000, cacheScope: "private" };
 /** 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, apiUrl } = 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");
-        }
+/**
+ * Wraps a tool handler so its outcome becomes a `CallToolResult` and every
+ * call is recorded. A throw is reported to the client as an errored tool
+ * result rather than a protocol error, which is what lets an agent read the
+ * message and retry.
+ */
+function wrapHandler(tool, apiUrl) {
+    const command = `tool ${tool.name}`.slice(0, 120);
+    return async (args) => {
         const start = Date.now();
-        const command = `tool ${tool.name}`.slice(0, 120);
         try {
-            const result = await tool.handler(args);
-            recordEvent({
-                surface: "mcp",
-                command,
-                exitCode: 0,
-                durationMs: Date.now() - start,
-            }, { apiUrl });
-            return response(id, {
+            const result = await tool.handler(args ?? {});
+            recordEvent({ surface: "mcp", command, exitCode: 0, durationMs: Date.now() - start }, { apiUrl });
+            return {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
                 structuredContent: result,
                 isError: false,
-            });
+            };
         }
         catch (err) {
             recordEvent({
@@ -65,82 +69,26 @@ export function createMcpServer(opts) {
             // Multi-file total failure: keep structuredContent so agents see every
             // per-file error, not only the first message string.
             if (err instanceof ToolBatchError) {
-                return response(id, {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify(err.structuredContent, null, 2),
-                        },
-                    ],
+                return {
+                    content: [{ type: "text", text: JSON.stringify(err.structuredContent, null, 2) }],
                     structuredContent: err.structuredContent,
                     isError: true,
-                });
+                };
             }
-            return response(id, {
-                content: [{ type: "text", text: toolErrorText(err) }],
-                isError: true,
-            });
+            return { 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));
-            }
-        },
     };
 }
+export function createMcpServer(opts) {
+    const { serverInfo, tools, apiUrl, validator } = opts;
+    const server = new McpServer(serverInfo, {
+        cacheHints: { "tools/list": TOOLS_LIST_CACHE_HINT },
+    });
+    for (const tool of tools) {
+        server.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: fromJsonSchema(tool.inputSchema, validator),
+        }, wrapHandler(tool, apiUrl));
+    }
+    return server;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,
@@ -57,6 +57,7 @@
     "provenance": true
   },
   "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
     "exif-reader": "^2.0.3",
     "opentype.js": "^2.0.0",
     "perfect-freehand": "^1.2.3",

package/dist/mcp/stdio.d.ts

@@ -1,3 +0,0 @@
-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

@@ -1,14 +0,0 @@
-/** 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");
-    }
-}