@toolgrain/mcp 0.2.0 → 0.3.0-alpha.1

package/src/tools/context.ts

@@ -18,6 +18,7 @@ import {
 } from "../context/registry.js";
 import { createContextScope } from "../context/scope.js";
 import type { DeepReadonly } from "./json-value.js";
+import type { ToolProgress } from "./progress.js";
 
 /** What the client reported about itself; unverified, so not a basis for security decisions. */
 export interface ToolClient {
@@ -47,6 +48,15 @@ export interface ToolContext {
   readonly signal: AbortSignal;
   /** Frozen request metadata; contains no verified authorization identity. */
   readonly request: ToolRequest;
+  /**
+   * Report request-scoped progress; safe to pass to helpers without binding.
+   * Await delivery/backpressure; updates are spaced at least 100 ms per invocation.
+   * Resolves without sending when no progress token or delivery channel exists,
+   * or after cancellation/completion. Active updates
+   * require finite values and strictly increasing progress; invalid updates reject.
+   * Delivery failure cancels the request and reaches transport diagnostics.
+   */
+  readonly reportProgress: (update: ToolProgress) => Promise<void>;
 }
 
 /** Optional metadata, cancellation, and provider bindings for a direct-call context. */
@@ -94,10 +104,12 @@ export function createToolContext(
   { client, ...request }: ToolRequest,
   auth?: AuthIdentity,
   providers: ContextRegistry = createContextRegistry(),
+  reportProgress: ToolContext["reportProgress"] = () => Promise.resolve(),
 ): ToolContext {
   const ctx = attachAuth(
     {
       signal,
+      reportProgress,
       request: Object.freeze({
         ...request,
         ...(client === undefined

package/src/tools/progress.ts

@@ -0,0 +1,119 @@
+import type { ProgressNotification, ProgressToken } from "@toolgrain/protocol";
+import { z } from "zod";
+import { abortable } from "../abort.js";
+
+/** One progress update; values are finite numbers and progress must strictly increase. */
+export interface ToolProgress {
+  /** Work completed so far, in application-defined units; the first value may be zero. */
+  readonly progress: number;
+  /** Optional total work, in the same units; omit when unknown. */
+  readonly total?: number;
+  /** Optional public status message sent to the client. */
+  readonly message?: string;
+}
+
+const update = z.object({
+  progress: z.number().finite(),
+  total: z.number().finite().optional(),
+  message: z.string().optional(),
+});
+
+/** Tokens share the request-ID wire format, but have a separate lifetime. */
+export function isProgressToken(token: unknown): token is ProgressToken {
+  return (
+    typeof token === "string" ||
+    (typeof token === "number" &&
+      Number.isFinite(token) &&
+      Number.isInteger(token))
+  );
+}
+
+/** Cancellation must release the timer as well as the awaiting handler. */
+function waitForProgress(milliseconds: number, signal: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", abort);
+      resolve();
+    }, milliseconds);
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+/** One invocation owns its reporter, ordering, and completion boundary. */
+export function createProgressReporter(
+  requestSignal: AbortSignal,
+  token: unknown,
+  send?: (message: ProgressNotification) => void | Promise<void>,
+) {
+  const lifetime = new AbortController();
+  const signal = AbortSignal.any([requestSignal, lifetime.signal]);
+  const validToken = isProgressToken(token);
+  let open = true;
+  let previous = Number.NEGATIVE_INFINITY;
+  let writes = Promise.resolve();
+  let lastSent = Number.NEGATIVE_INFINITY;
+  const report = (value: ToolProgress): Promise<void> => {
+    if (!open || signal.aborted || !validToken || !send)
+      return Promise.resolve();
+    const parsed = update.safeParse(value);
+    if (!parsed.success)
+      return Promise.reject(new TypeError("Invalid progress update"));
+    if (parsed.data.progress <= previous)
+      return Promise.reject(new TypeError("Progress must strictly increase"));
+    previous = parsed.data.progress;
+    const message: ProgressNotification = {
+      jsonrpc: "2.0",
+      method: "notifications/progress",
+      params: {
+        progress: parsed.data.progress,
+        ...(parsed.data.total === undefined
+          ? {}
+          : { total: parsed.data.total }),
+        ...(parsed.data.message === undefined
+          ? {}
+          : { message: parsed.data.message }),
+        progressToken: token as ProgressToken,
+      },
+    };
+    const write = writes.then(async () => {
+      if (!signal.aborted) {
+        // Pace each operation without dropping updates or bypassing backpressure.
+        let remaining = 100 - (performance.now() - lastSent);
+        while (remaining > 0) {
+          await waitForProgress(Math.ceil(remaining), signal);
+          remaining = 100 - (performance.now() - lastSent);
+        }
+        await abortable(
+          Promise.resolve().then(() => {
+            if (!signal.aborted) {
+              lastSent = performance.now();
+              return send(message);
+            }
+          }),
+          signal,
+        );
+      }
+    });
+    // The awaiting handler observes failures; keep the queue usable for cleanup.
+    writes = write.catch(() => {});
+    return write;
+  };
+  return {
+    report,
+    async finish() {
+      open = false;
+      await writes;
+    },
+    close() {
+      open = false;
+      lifetime.abort(
+        new DOMException("Progress reporting closed", "AbortError"),
+      );
+    },
+  };
+}

package/src/transport.ts

@@ -1,4 +1,7 @@
-import type { ProtocolResponse } from "@toolgrain/protocol";
+import type {
+  ProgressNotification,
+  ProtocolResponse,
+} from "@toolgrain/protocol";
 import type { Server } from "./server.js";
 
 /** Callbacks are synchronous; message processing runs independently. */
@@ -23,10 +26,10 @@ export interface Transport {
    */
   start(callbacks: TransportCallbacks): Promise<void>;
   /**
-   * Send one protocol response, resolving after the adapter's write/backpressure handling.
-   * @param message - Response envelope already converted for the client's protocol revision.
+   * Send one response or progress notification, resolving after write/backpressure handling.
+   * @param message - Envelope already converted for the client's protocol revision.
    */
-  send(message: ProtocolResponse): Promise<void>;
+  send(message: ProtocolResponse | ProgressNotification): Promise<void>;
   /** Release adapter-owned resources; closing is terminal and must tolerate repeated calls. */
   close(): Promise<void>;
 }

package/dist/auth/abort.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/auth/abort.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,CAAC,EACzB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC,CASZ"}

package/dist/auth/abort.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/auth/abort.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,UAAU,SAAS,CACvB,IAAgB,EAChB,MAAmB;IAEnB,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,OAAO;YAAE,KAAK,EAAE,CAAC;;YACvB,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,IAAI;aACD,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC;aACrB,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC"}