@toolgrain/mcp 0.3.0-alpha.0 → 0.3.0-alpha.2

package/dist/tools/progress.js

@@ -5,15 +5,39 @@ const update = z.object({
     total: z.number().finite().optional(),
     message: z.string().optional(),
 });
-/** One invocation owns its reporter, ordering, and completion boundary. */
-export function createProgressReporter(signal, token, send) {
-    const validToken = typeof token === "string" ||
+/** Tokens share the request-ID wire format, but have a separate lifetime. */
+export function isProgressToken(token) {
+    return (typeof token === "string" ||
         (typeof token === "number" &&
             Number.isFinite(token) &&
-            Number.isInteger(token));
+            Number.isInteger(token)));
+}
+/** Cancellation must release the timer as well as the awaiting handler. */
+function waitForProgress(milliseconds, signal) {
+    return new Promise((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, token, send) {
+    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) => {
         if (!open || signal.aborted || !validToken || !send)
             return Promise.resolve();
@@ -38,11 +62,20 @@ export function createProgressReporter(signal, token, send) {
             },
         };
         const write = writes.then(async () => {
-            if (!signal.aborted)
+            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)
+                    if (!signal.aborted) {
+                        lastSent = performance.now();
                         return send(message);
+                    }
                 }), signal);
+            }
         });
         // The awaiting handler observes failures; keep the queue usable for cleanup.
         writes = write.catch(() => { });
@@ -56,6 +89,7 @@ export function createProgressReporter(signal, token, send) {
         },
         close() {
             open = false;
+            lifetime.abort(new DOMException("Progress reporting closed", "AbortError"));
         },
     };
 }

package/dist/tools/progress.js.map

@@ -1 +1 @@
-{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/tools/progress.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/tools/progress.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAYxC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IACtB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE;IAC7B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEH,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,OAAO,KAAK,KAAK,QAAQ;YACxB,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YACtB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,SAAS,eAAe,CAAC,YAAoB,EAAE,MAAmB;IAChE,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAC3C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,YAAY,CAAC,CAAC;QACjB,IAAI,MAAM,CAAC,OAAO;YAAE,KAAK,EAAE,CAAC;;YACvB,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,sBAAsB,CACpC,aAA0B,EAC1B,KAAc,EACd,IAA8D;IAE9D,MAAM,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IACvC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACjE,MAAM,UAAU,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,IAAI,QAAQ,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACxC,IAAI,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/B,IAAI,QAAQ,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACxC,MAAM,MAAM,GAAG,CAAC,KAAmB,EAAiB,EAAE;QACpD,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI;YACjD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,OAAO;YACjB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,yBAAyB,CAAC,CAAC,CAAC;QAClE,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,QAAQ;YAClC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC,CAAC;QAC1E,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;QAChC,MAAM,OAAO,GAAyB;YACpC,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,wBAAwB;YAChC,MAAM,EAAE;gBACN,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ;gBAC9B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS;oBACjC,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACjC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS;oBACnC,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACrC,aAAa,EAAE,KAAsB;aACtC;SACF,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YACnC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,0EAA0E;gBAC1E,IAAI,SAAS,GAAG,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,CAAC;gBACrD,OAAO,SAAS,GAAG,CAAC,EAAE,CAAC;oBACrB,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC;oBACpD,SAAS,GAAG,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,CAAC;gBACnD,CAAC;gBACD,MAAM,SAAS,CACb,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;oBAC1B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;wBACpB,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;wBAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;oBACvB,CAAC;gBACH,CAAC,CAAC,EACF,MAAM,CACP,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;QACH,6EAA6E;QAC7E,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,OAAO;QACL,MAAM;QACN,KAAK,CAAC,MAAM;YACV,IAAI,GAAG,KAAK,CAAC;YACb,MAAM,MAAM,CAAC;QACf,CAAC;QACD,KAAK;YACH,IAAI,GAAG,KAAK,CAAC;YACb,QAAQ,CAAC,KAAK,CACZ,IAAI,YAAY,CAAC,2BAA2B,EAAE,YAAY,CAAC,CAC5D,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/rich-result.d.ts

@@ -1,7 +1,7 @@
 import type { ContentBlock, MetaObject } from "@toolgrain/protocol";
 import type { DeepReadonly, JsonCompatible } from "./json-value.js";
 /** Explicit MCP content and optional structured data, wrapped with `mcpResult()`. */
-export interface McpResultOptions<Structured = unknown> {
+export interface McpResultOptions<Structured = unknown, Meta extends MetaObject = MetaObject> {
     /** Content blocks for the client; readonly authoring arrays are accepted. */
     content: readonly DeepReadonly<ContentBlock>[];
     /** JSON-compatible data; required for successful rich results with a declared output schema. */
@@ -9,35 +9,35 @@ export interface McpResultOptions<Structured = unknown> {
     /** Marks an expected, client-visible tool failure; omitted or false indicates success. */
     isError?: boolean;
     /** Optional protocol result metadata, distinct from application structured data. */
-    _meta?: MetaObject;
+    _meta?: Meta;
 }
 /**
  * Branded rich-result wrapper recognized by compatible Toolgrain package copies.
  * Use `mcpResult()` to construct one; a plain object with the same fields remains application data.
  */
-export declare class McpResult<Structured> {
+export declare class McpResult<Structured, Meta extends MetaObject = MetaObject> {
     /** Explicit MCP result envelope, before server validation and revision-specific conversion. */
-    readonly value: McpResultOptions<Structured>;
+    readonly value: McpResultOptions<Structured, Meta>;
     constructor(
     /** Explicit MCP result envelope, before server validation and revision-specific conversion. */
-    value: McpResultOptions<Structured>);
+    value: McpResultOptions<Structured, Meta>);
     /** Structural brand shared by package copies; object spreads do not keep it. */
     "~toolgrain"(): "result@1";
 }
 /** Recognize results created by any compatible copy of this package. */
 export declare function isMcpResult(value: unknown): value is McpResult<unknown>;
 /** Explicit, client-visible tool error; structured data may be omitted for text-only errors. */
-export type McpErrorResult<Structured = never> = McpResult<Structured> & {
+export type McpErrorResult<Structured = never, Meta extends MetaObject = MetaObject> = McpResult<Structured, Meta> & {
     /** Envelope statically marked as an error. */
-    readonly value: McpResultOptions<Structured> & {
+    readonly value: McpResultOptions<Structured, Meta> & {
         /** Explicit expected-failure marker, preserved in the MCP result. */
         isError: true;
     };
 };
 /** A result whose structured data is present, as required by an output schema. */
-export type McpStructuredResult<Structured> = McpResult<Structured> & {
+export type McpStructuredResult<Structured, Meta extends MetaObject = MetaObject> = McpResult<Structured, Meta> & {
     /** Envelope with required application structured data. */
-    readonly value: McpResultOptions<Structured> & {
+    readonly value: McpResultOptions<Structured, Meta> & {
         /** Structured value validated against the tool's output schema when one is declared. */
         structuredContent: Structured;
     };
@@ -48,45 +48,45 @@ export type McpStructuredResult<Structured> = McpResult<Structured> & {
  * @param value - Error content and JSON-compatible data, parsed by any declared output schema.
  * @returns A branded result typed as both an error and a structured result.
  */
-export declare function mcpResult<Structured = never>(value: McpResultOptions<Structured> & {
+export declare function mcpResult<Structured = never, const Meta extends MetaObject = MetaObject>(value: McpResultOptions<Structured, Meta> & {
     /** Mark this result as an expected, client-visible tool failure. */
     isError: true;
     /** Structured error data, subject to output-schema validation when declared. */
     structuredContent: Structured;
-}): McpErrorResult<Structured> & McpStructuredResult<Structured>;
+}): McpErrorResult<Structured, Meta> & McpStructuredResult<Structured, Meta>;
 /**
  * Wrap a text/content-only public tool error, allowed even when the tool declares output.
  * @param value - Explicit error content without structured application data.
  * @returns A branded error result whose `isError` flag is statically true.
  */
-export declare function mcpResult(value: McpResultOptions<never> & {
+export declare function mcpResult<Structured = never, const Meta extends MetaObject = MetaObject>(value: McpResultOptions<never, Meta> & {
     /** Mark this result as an expected, client-visible tool failure. */
     isError: true;
-}): McpErrorResult<never>;
+}): McpErrorResult<Structured, Meta>;
 /**
  * Wrap a public tool error with an optional structured-data contract.
  * @param value - Error content and any JSON-compatible structured data.
  * @returns A branded error result; provided structured data still undergoes output validation.
  */
-export declare function mcpResult<Structured>(value: McpResultOptions<Structured> & {
+export declare function mcpResult<Structured, const Meta extends MetaObject = MetaObject>(value: McpResultOptions<Structured, Meta> & {
     /** Mark this result as an expected, client-visible tool failure. */
     isError: true;
-}): McpErrorResult<Structured>;
+}): McpErrorResult<Structured, Meta>;
 /**
  * Wrap rich content with required structured application data.
  * @param value - Client content and JSON-compatible data; a successful output-schema result needs both.
  * @returns A branded structured result; the server validates and converts it for the selected revision.
  */
-export declare function mcpResult<Structured>(value: McpResultOptions<Structured> & {
+export declare function mcpResult<Structured, const Meta extends MetaObject = MetaObject>(value: McpResultOptions<Structured, Meta> & {
     /** Required application data, parsed by the declared output schema when present. */
     structuredContent: Structured;
-}): McpStructuredResult<Structured>;
+}): McpStructuredResult<Structured, Meta>;
 /**
  * Wrap explicit client content without structured application data.
  * @param value - Rich content; successful results of this form require a tool without an output schema.
  * @returns A branded MCP result. Ordinary result-shaped objects are not treated as rich results.
  */
-export declare function mcpResult(value: McpResultOptions<never>): McpResult<never>;
+export declare function mcpResult<Structured = never, const Meta extends MetaObject = MetaObject>(value: McpResultOptions<never, Meta>): McpResult<Structured, Meta>;
 /**
  * Explicitly return MCP content instead of ordinary application JSON.
  * The server validates the envelope, parses supplied output data, and converts it for the protocol revision.
@@ -94,5 +94,5 @@ export declare function mcpResult(value: McpResultOptions<never>): McpResult<nev
  * @param value - Content blocks, optional structured data, an error marker, and protocol metadata.
  * @returns A frozen result wrapper; content is checked during server invocation.
  */
-export declare function mcpResult<Structured = never>(value: McpResultOptions<Structured>): McpResult<Structured>;
+export declare function mcpResult<Structured = never, const Meta extends MetaObject = MetaObject>(value: McpResultOptions<Structured, Meta>): McpResult<Structured, Meta>;
 //# sourceMappingURL=rich-result.d.ts.map

package/dist/tools/rich-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rich-result.d.ts","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rich-result.d.ts","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"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"}

package/dist/tools/rich-result.js.map

@@ -1 +1 @@
-{"version":3,"file":"rich-result.js","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"AAeA,kFAAkF;AAClF,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAE3D;;;GAGG;AACH,MAAM,OAAO,SAAS;IAGT,KAAK;IAFhB;IACE,+FAA+F;IACtF,KAAmC;qBAAnC,KAAK;QAEd,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,gFAAgF;IAChF,YAAY;QACV,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AACD,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1E,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAsC,CAAC,YAAY,CAAC,KAAK,IAAI,CAC/D,CAAC;AACJ,CAAC;AAmFD,MAAM,UAAU,SAAS,CACvB,KAAmC;IAEnC,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"rich-result.js","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"AAkBA,kFAAkF;AAClF,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAE3D;;;GAGG;AACH,MAAM,OAAO,SAAS;IAGT,KAAK;IAFhB;IACE,+FAA+F;IACtF,KAAyC;qBAAzC,KAAK;QAEd,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,gFAAgF;IAChF,YAAY;QACV,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AACD,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1E,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAsC,CAAC,YAAY,CAAC,KAAK,IAAI,CAC/D,CAAC;AACJ,CAAC;AAyGD,MAAM,UAAU,SAAS,CAGvB,KAAyC;IACzC,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolgrain/mcp",
-  "version": "0.3.0-alpha.0",
+  "version": "0.3.0-alpha.2",
   "description": "Define reusable, typed MCP tools and servers with Zod validation.",
   "license": "MIT",
   "repository": {
@@ -59,7 +59,7 @@
     "@toolgrain/repo-tools": "0.0.0"
   },
   "dependencies": {
-    "@toolgrain/protocol": "0.3.0-alpha.0"
+    "@toolgrain/protocol": "0.3.0-alpha.2"
   },
   "engines": {
     "node": "^24.20.0",

package/src/apps.ts

@@ -0,0 +1,23 @@
+import { APPS_EXTENSION_ID, APPS_MIME_TYPE } from "@toolgrain/protocol/apps";
+import type { ToolContext } from "./tools/context.js";
+
+/** Advisory client claim; never an authorization decision. */
+export type AppSupport = "supported" | "not-advertised" | "unknown";
+
+/**
+ * Read the current request's MCP Apps claim. Legacy independent HTTP has no
+ * retained client capabilities and returns unknown. A claim is not verified.
+ */
+export function getAppSupport(ctx: ToolContext): AppSupport {
+  const capabilities = ctx.request.client?.capabilities;
+  if (!capabilities) return "unknown";
+  const extensions = (capabilities as { extensions?: unknown }).extensions;
+  if (typeof extensions !== "object" || extensions === null)
+    return "not-advertised";
+  const ui = (extensions as Record<string, unknown>)[APPS_EXTENSION_ID];
+  if (typeof ui !== "object" || ui === null) return "not-advertised";
+  const mimeTypes = (ui as { mimeTypes?: unknown }).mimeTypes;
+  return Array.isArray(mimeTypes) && mimeTypes.includes(APPS_MIME_TYPE)
+    ? "supported"
+    : "not-advertised";
+}

package/src/connection.ts

@@ -1,4 +1,5 @@
 import {
+  INVALID_PARAMS,
   INVALID_REQUEST,
   PARSE_ERROR,
   type ProgressNotification,
@@ -13,6 +14,7 @@ import { decode } from "./protocol/decode.js";
 import type { Request } from "./protocol/messages.js";
 import { protocolError } from "./protocol/responses.js";
 import type { Server } from "./server.js";
+import { isProgressToken } from "./tools/progress.js";
 import type {
   RequestTransport,
   Transport,
@@ -189,6 +191,19 @@ class Connection implements ConnectionLifecycle {
       );
       return;
     }
+    const token = (request.params?._meta as Record<string, unknown> | undefined)
+      ?.progressToken;
+    if (isProgressToken(token) && !pending.claimProgress(token)) {
+      pending.finish();
+      await this.send(
+        protocolError(
+          INVALID_PARAMS,
+          "Progress token is already in use",
+          request.id,
+        ),
+      );
+      return;
+    }
     const initialization = this.legacy.begin(request, prepared.protocolVersion);
     try {
       const response = await executeRequest(

package/src/dispatcher.ts

@@ -16,6 +16,7 @@ import { errorResponse as legacyErrorResponse } from "./legacy/responses.js";
 import { createModernDispatcher } from "./modern/dispatcher.js";
 import type { Request } from "./protocol/messages.js";
 import { validateVersionContext } from "./protocol/version-metadata.js";
+import type { ResourceRegistry } from "./resources/registry.js";
 import type { ToolAdapter } from "./tools/adapter.js";
 import type { ToolClient, ToolContext } from "./tools/context.js";
 
@@ -41,18 +42,21 @@ export function createDispatcher(
   identity: Implementation,
   instructions?: string,
   providers?: ContextRegistry,
+  resources?: ResourceRegistry,
 ): Dispatcher {
   const legacy = createLegacyDispatcher(
     tools,
     identity,
     instructions,
     providers,
+    resources,
   );
   const modern = createModernDispatcher(
     tools,
     identity,
     instructions,
     providers,
+    resources,
   );
   return (request, scope, protocolVersion) => {
     validateVersionContext(request, protocolVersion);

package/src/index.ts

@@ -1,3 +1,5 @@
+export type { AppSupport } from "./apps.js";
+export { getAppSupport } from "./apps.js";
 export { validateTokenAudience } from "./auth/audience.js";
 export { createAuthAccessor } from "./auth/context.js";
 export type { AuthErrorCode } from "./auth/errors.js";
@@ -14,6 +16,13 @@ export { authUrl as validateAuthUrl } from "./auth/url.js";
 export type { ContextProvider } from "./context/definition.js";
 export { createContext } from "./context/definition.js";
 export type { ToolErrorDetails } from "./diagnostics.js";
+export type {
+  Resource,
+  ResourceDefinition,
+  ResourceMetadata,
+  ResourceReadResult,
+} from "./resources/definition.js";
+export { resource } from "./resources/definition.js";
 export type { HandleOptions, Server, ServerOptions } from "./server.js";
 export { createServer } from "./server.js";
 export type {

package/src/legacy/dispatcher.ts

@@ -10,7 +10,15 @@ import type { RequestScope } from "../dispatcher.js";
 import type { Request } from "../protocol/messages.js";
 import { ProtocolError } from "../protocol/responses.js";
 import { hasProtocolVersionMetadata } from "../protocol/version-metadata.js";
+import type { ResourceRegistry } from "../resources/registry.js";
+import {
+  listResources,
+  listResourceTemplates,
+  readResource,
+  requireResources,
+} from "../resources/requests.js";
 import type { ToolAdapter } from "../tools/adapter.js";
+import type { ToolContext } from "../tools/context.js";
 import { createToolContext } from "../tools/context.js";
 import { callTool, initialize, listTools, ping } from "./handlers.js";
 import { successResponse } from "./responses.js";
@@ -33,15 +41,36 @@ export function createLegacyDispatcher(
   identity: Implementation,
   instructions?: string,
   providers?: ContextRegistry,
+  resources?: ResourceRegistry,
 ) {
   return async (
     request: Request,
     scope: RequestScope,
   ): Promise<JSONRPCResponse | undefined> => {
+    const context = (params: {
+      _meta?: Record<string, unknown> | undefined;
+    }): ToolContext =>
+      createToolContext(
+        scope.signal,
+        {
+          id: request.id,
+          protocolVersion: LEGACY_PROTOCOL_VERSION,
+          ...(scope.client === undefined ? {} : { client: scope.client }),
+          meta: params._meta ?? {},
+        },
+        scope.auth,
+        providers,
+        scope.reportProgress,
+      );
     let result: Result | undefined;
     switch (request.method) {
       case "initialize":
-        result = initialize(request.params, identity, instructions);
+        result = initialize(
+          request.params,
+          identity,
+          instructions,
+          resources !== undefined,
+        );
         break;
       case "ping":
         result = ping(request.params);
@@ -50,19 +79,32 @@ export function createLegacyDispatcher(
         result = listTools(request.params, tools);
         break;
       case "tools/call":
-        result = await callTool(request.params, tools, (params) =>
-          createToolContext(
-            scope.signal,
-            {
-              id: request.id,
-              protocolVersion: LEGACY_PROTOCOL_VERSION,
-              ...(scope.client === undefined ? {} : { client: scope.client }),
-              meta: params._meta ?? {},
-            },
-            scope.auth,
-            providers,
-            scope.reportProgress,
+        result = await callTool(request.params, tools, context);
+        break;
+      case "resources/list": {
+        const listed = listResources(
+          request.params,
+          requireResources(resources),
+        );
+        result = {
+          resources: listed.resources.map(
+            ({ icons: _icons, ...entry }) => entry,
           ),
+        };
+        break;
+      }
+      case "resources/templates/list":
+        result = listResourceTemplates(
+          request.params,
+          requireResources(resources),
+        );
+        break;
+      case "resources/read":
+        result = await readResource(
+          request.params,
+          requireResources(resources),
+          context,
+          -32002,
         );
         break;
       default:

package/src/legacy/handlers.ts

@@ -24,6 +24,7 @@ export function initialize(
   params: unknown,
   identity: Implementation,
   instructions?: string,
+  resources = false,
 ): InitializeResult {
   if (!initializeParams.safeParse(params).success)
     throw new ProtocolError(
@@ -32,7 +33,7 @@ export function initialize(
     );
   return {
     protocolVersion: LEGACY_PROTOCOL_VERSION,
-    capabilities: { tools: {} },
+    capabilities: { tools: {}, ...(resources ? { resources: {} } : {}) },
     serverInfo: { ...identity },
     ...(instructions === undefined ? {} : { instructions }),
   };

package/src/modern/dispatcher.ts

@@ -13,17 +13,27 @@ import type { ContextRegistry } from "../context/registry.js";
 import type { RequestScope } from "../dispatcher.js";
 import type { Request } from "../protocol/messages.js";
 import { ProtocolError } from "../protocol/responses.js";
+import type { ResourceRegistry } from "../resources/registry.js";
+import {
+  listResources,
+  listResourceTemplates,
+  readResource,
+  requireResources,
+} from "../resources/requests.js";
 import type { ToolAdapter } from "../tools/adapter.js";
+import type { ToolContext } from "../tools/context.js";
 import { createToolContext, toolClient } from "../tools/context.js";
 import { callTool, discover, listTools } from "./handlers.js";
 import { metadata } from "./metadata.js";
 import { successResponse } from "./responses.js";
+import { resourceResult } from "./results.js";
 
 export function createModernDispatcher(
   tools: ToolAdapter,
   identity: Implementation,
   instructions?: string,
   providers?: ContextRegistry,
+  resources?: ResourceRegistry,
 ) {
   return async (
     request: Request,
@@ -39,37 +49,63 @@ export function createModernDispatcher(
         "Unsupported protocol version",
         { supported: [...SUPPORTED_PROTOCOL_VERSIONS], requested: revision },
       );
+    const context = (params: {
+      _meta?: Record<string, unknown> | undefined;
+    }): ToolContext =>
+      createToolContext(
+        scope.signal,
+        {
+          id: request.id,
+          protocolVersion: PROTOCOL_VERSION,
+          client: toolClient(
+            parsed.data["io.modelcontextprotocol/clientInfo"] as
+              | Implementation
+              | undefined,
+            parsed.data[
+              "io.modelcontextprotocol/clientCapabilities"
+            ] as ClientCapabilities,
+          ),
+          meta: params._meta ?? {},
+        },
+        scope.auth,
+        providers,
+        scope.reportProgress,
+      );
     let result: Result | undefined;
     switch (request.method) {
       case "server/discover":
-        result = discover(request.params, instructions);
+        result = discover(
+          request.params,
+          instructions,
+          resources !== undefined,
+        );
         break;
       case "tools/list":
         result = listTools(request.params, tools);
         break;
       case "tools/call":
-        result = await callTool(request.params, tools, (params) =>
-          createToolContext(
-            scope.signal,
-            {
-              id: request.id,
-              protocolVersion: PROTOCOL_VERSION,
-              client: toolClient(
-                parsed.data["io.modelcontextprotocol/clientInfo"] as
-                  | Implementation
-                  | undefined,
-                parsed.data[
-                  "io.modelcontextprotocol/clientCapabilities"
-                ] as ClientCapabilities,
-              ),
-              meta: params._meta ?? {},
-            },
-            scope.auth,
-            providers,
-            scope.reportProgress,
-          ),
+        result = await callTool(request.params, tools, context);
+        break;
+      case "resources/list":
+        result = resourceResult(
+          listResources(request.params, requireResources(resources)),
+        );
+        break;
+      case "resources/templates/list":
+        result = resourceResult(
+          listResourceTemplates(request.params, requireResources(resources)),
+        );
+        break;
+      case "resources/read": {
+        const value = await readResource(
+          request.params,
+          requireResources(resources),
+          context,
+          INVALID_PARAMS,
         );
+        result = value === undefined ? undefined : resourceResult(value);
         break;
+      }
       default:
         throw new ProtocolError(METHOD_NOT_FOUND, "Method not found");
     }

package/src/modern/handlers.ts

@@ -14,6 +14,7 @@ import { toolResult } from "./results.js";
 export function discover(
   params: unknown,
   instructions?: string,
+  resources = false,
 ): DiscoverResult {
   if (!commonParams.safeParse(params).success)
     throw new ProtocolError(INVALID_PARAMS, "Invalid discovery parameters");
@@ -22,7 +23,7 @@ export function discover(
     ttlMs: 0,
     cacheScope: "private",
     supportedVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
-    capabilities: { tools: {} },
+    capabilities: { tools: {}, ...(resources ? { resources: {} } : {}) },
     ...(instructions === undefined ? {} : { instructions }),
   };
 }

package/src/modern/results.ts

@@ -4,3 +4,13 @@ import type { ToolExecutionResult } from "../tools/results.js";
 export function toolResult(result: ToolExecutionResult): CallToolResult {
   return { resultType: "complete", ...result };
 }
+
+/** Resource results do not enable caching until applications have a cache-policy API. */
+export function resourceResult<Result extends object>(result: Result) {
+  return {
+    ...result,
+    resultType: "complete" as const,
+    ttlMs: 0,
+    cacheScope: "private" as const,
+  };
+}

package/src/pending-requests.ts

@@ -1,17 +1,33 @@
-import type { RequestId } from "@toolgrain/protocol";
+import type { ProgressToken, RequestId } from "@toolgrain/protocol";
 
 /** Owns duplicate detection and cancellation signals for in-flight requests. */
 export function createPendingRequests(isOpen: () => boolean) {
   const pending = new Map<RequestId, AbortController>();
+  const progressTokens = new Set<ProgressToken>();
   return {
     begin(id: RequestId) {
       if (pending.has(id)) return;
       const controller = new AbortController();
       pending.set(id, controller);
+      let releaseProgress: (() => void) | undefined;
       return {
         signal: controller.signal,
         isActive: () => isOpen() && !controller.signal.aborted,
+        claimProgress(token: ProgressToken) {
+          if (progressTokens.has(token)) return false;
+          progressTokens.add(token);
+          releaseProgress = () => {
+            progressTokens.delete(token);
+            controller.signal.removeEventListener("abort", release);
+            releaseProgress = undefined;
+          };
+          // Aborting releases the token even if the cancelled handler keeps running.
+          const release = () => releaseProgress?.();
+          controller.signal.addEventListener("abort", release, { once: true });
+          return true;
+        },
         finish: () => {
+          releaseProgress?.();
           pending.delete(id);
         },
       };