@toolgrain/mcp 0.3.0-alpha.1 → 0.3.0-alpha.3

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/resources/definition.ts

@@ -0,0 +1,92 @@
+import type {
+  BlobResourceContents,
+  MetaObject,
+  Resource as ProtocolResource,
+  TextResourceContents,
+} from "@toolgrain/protocol";
+import type { ToolContext } from "../tools/context.js";
+import type { DeepReadonly } from "../tools/json-value.js";
+
+/** Readonly resource identity and display metadata, copied during server registration. */
+export type ResourceMetadata = DeepReadonly<ProtocolResource>;
+
+/** Explicit resource contents; each item supplies its own URI and exactly one payload. */
+export interface ResourceReadResult {
+  /** Text or base64 binary entries; an existing resource may return an empty array. */
+  readonly contents: readonly (
+    | (DeepReadonly<TextResourceContents> & { readonly blob?: never })
+    | (DeepReadonly<BlobResourceContents> & { readonly text?: never })
+  )[];
+  /** Optional result metadata, separate from each content item's metadata. */
+  readonly _meta?: DeepReadonly<MetaObject>;
+}
+
+type ReadResult = ResourceReadResult | PromiseLike<ResourceReadResult>;
+
+/** A fixed resource and its application-owned reader. */
+export interface ResourceDefinition<Result extends ReadResult = ReadResult>
+  extends ResourceMetadata {
+  /**
+   * Read this URI using the request's auth, providers, and cancellation signal.
+   * Direct calls bypass server authorization and result validation.
+   */
+  readonly read: (uri: string, ctx: ToolContext) => Result;
+}
+
+export const RESOURCE_METADATA_KEYS = [
+  "uri",
+  "name",
+  "title",
+  "description",
+  "mimeType",
+  "annotations",
+  "size",
+  "icons",
+  "_meta",
+] as const;
+const brand = Symbol.for("@toolgrain/mcp/resource@1");
+
+/** Frozen reusable definition returned by `resource()`; direct reads remain raw. */
+export type Resource<Result extends ReadResult = ReadResult> =
+  ResourceDefinition<Result> & ResourceValue;
+
+class ResourceValue {
+  constructor(definition: ResourceDefinition) {
+    for (const key of [...RESOURCE_METADATA_KEYS, "read"] as const) {
+      const value = definition[key];
+      if (value !== undefined)
+        Object.defineProperty(this, key, { value, enumerable: true });
+    }
+    Object.freeze(this);
+  }
+
+  /** Structural brand shared by compatible package copies; object spreads drop it. */
+  "~toolgrain"(): "resource@1" {
+    return "resource@1";
+  }
+}
+Object.defineProperty(ResourceValue.prototype, brand, { value: true });
+
+export function isResource(value: unknown): value is Resource {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { [brand]?: unknown })[brand] === true
+  );
+}
+
+/**
+ * Declare a reusable fixed-URI resource without reading its contents.
+ * Registration validates and snapshots metadata; server reads validate and copy results.
+ * No URI is fetched or mapped to a filesystem automatically.
+ * @param definition - Absolute URI, display metadata, and synchronous or async reader.
+ * @returns A frozen definition preserving the reader's inferred return type.
+ * @throws `TypeError` if the reader is not a function.
+ */
+export function resource<Result extends ReadResult>(
+  definition: ResourceDefinition<Result>,
+): Resource<Result> {
+  if (typeof definition?.read !== "function")
+    throw new TypeError("Resources require a read function");
+  return new ResourceValue(definition) as Resource<Result>;
+}

package/src/resources/registry.ts

@@ -0,0 +1,72 @@
+import {
+  INTERNAL_ERROR,
+  type Resource as ProtocolResource,
+} from "@toolgrain/protocol";
+import { type ErrorHandler, reportError } from "../diagnostics.js";
+import { ProtocolError } from "../protocol/responses.js";
+import type { ToolContext } from "../tools/context.js";
+import { assertJSON } from "../tools/json-value.js";
+import {
+  isResource,
+  RESOURCE_METADATA_KEYS,
+  type Resource,
+} from "./definition.js";
+import {
+  copyReadResult,
+  type ResourceExecutionResult,
+  resourceMetadata,
+} from "./validation.js";
+
+type Reader = (
+  ctx: ToolContext,
+) => Promise<ResourceExecutionResult | undefined>;
+export interface ResourceRegistry {
+  list(): ProtocolResource[];
+  reader(uri: string): Reader | undefined;
+}
+
+export function createResourceRegistry(
+  definitions: readonly Resource[],
+  onError?: ErrorHandler,
+): ResourceRegistry {
+  const entries = new Map<
+    string,
+    { metadata: ProtocolResource; read: Reader }
+  >();
+  for (const definition of definitions) {
+    if (!isResource(definition))
+      throw new TypeError("Resources must be created with resource()");
+    const fields: Record<string, unknown> = {};
+    for (const key of RESOURCE_METADATA_KEYS)
+      if (definition[key] !== undefined) fields[key] = definition[key];
+    assertJSON(fields);
+    const metadata = resourceMetadata.parse(
+      structuredClone(fields),
+    ) as ProtocolResource;
+    if (entries.has(metadata.uri))
+      throw new TypeError(`Duplicate resource URI: ${metadata.uri}`);
+    if (typeof definition.read !== "function")
+      throw new TypeError("Resources require a read function");
+    entries.set(metadata.uri, {
+      metadata,
+      async read(ctx) {
+        if (ctx.signal.aborted) return;
+        try {
+          const value = await definition.read(metadata.uri, ctx);
+          if (ctx.signal.aborted) return;
+          const result = copyReadResult(value);
+          return ctx.signal.aborted ? undefined : result;
+        } catch (error) {
+          if (ctx.signal.aborted) return;
+          reportError(onError, error);
+          throw new ProtocolError(INTERNAL_ERROR, "Internal error");
+        }
+      },
+    });
+  }
+  return {
+    list: () =>
+      structuredClone(Array.from(entries.values(), ({ metadata }) => metadata)),
+    reader: (uri) => entries.get(uri)?.read,
+  };
+}

package/src/resources/requests.ts

@@ -0,0 +1,59 @@
+import { INVALID_PARAMS, METHOD_NOT_FOUND } from "@toolgrain/protocol";
+import { z } from "zod";
+import { object } from "../protocol/messages.js";
+import { ProtocolError } from "../protocol/responses.js";
+import type { ToolContext } from "../tools/context.js";
+import type { ResourceRegistry } from "./registry.js";
+import { resourceUri } from "./validation.js";
+
+const listParams = z.looseObject({
+  _meta: object.optional(),
+  cursor: z.string().optional(),
+});
+const readParams = z.looseObject({
+  _meta: object.optional(),
+  uri: resourceUri,
+});
+
+export function requireResources(
+  resources: ResourceRegistry | undefined,
+): ResourceRegistry {
+  if (!resources) throw new ProtocolError(METHOD_NOT_FOUND, "Method not found");
+  return resources;
+}
+
+function validateList(params: unknown) {
+  const parsed = listParams.safeParse(params ?? {});
+  if (!parsed.success || parsed.data.cursor !== undefined)
+    throw new ProtocolError(INVALID_PARAMS, "Invalid resource list parameters");
+}
+
+export function listResources(params: unknown, resources: ResourceRegistry) {
+  validateList(params);
+  return { resources: resources.list() };
+}
+
+export function listResourceTemplates(
+  params: unknown,
+  _resources: ResourceRegistry,
+) {
+  validateList(params);
+  return { resourceTemplates: [] };
+}
+
+export async function readResource(
+  params: unknown,
+  resources: ResourceRegistry,
+  ctx: (params: { _meta?: Record<string, unknown> | undefined }) => ToolContext,
+  notFoundCode: number,
+) {
+  const parsed = readParams.safeParse(params);
+  if (!parsed.success)
+    throw new ProtocolError(INVALID_PARAMS, "Invalid resource read parameters");
+  const read = resources.reader(parsed.data.uri);
+  if (!read)
+    throw new ProtocolError(notFoundCode, "Resource not found", {
+      uri: parsed.data.uri,
+    });
+  return read(ctx(parsed.data));
+}

package/src/resources/validation.ts

@@ -0,0 +1,82 @@
+import type { ReadResourceResult } from "@toolgrain/protocol";
+import { z } from "zod";
+import { icon } from "../protocol/icon.js";
+import { object } from "../protocol/messages.js";
+import { assertJSON } from "../tools/json-value.js";
+export type ResourceExecutionResult = Pick<
+  ReadResourceResult,
+  "contents" | "_meta"
+>;
+
+// RFC 3986 components: percent-encoded bytes, unreserved characters, and sub-delimiters.
+const atom = "(?:[A-Za-z0-9._~-]|%[A-Fa-f0-9]{2}|[!$&'()*+,;=])";
+const path = new RegExp(`^(?:${atom}|[:@/])*$`);
+const queryOrFragment = new RegExp(`^(?:${atom}|[:@/?])*$`);
+const authority = new RegExp(
+  `^(?:(?:${atom}|:)*@)?(?:${atom}*|\\[([^\\]]+)\\])(?::[0-9]*)?$`,
+);
+const ipFuture = /^v[A-Fa-f0-9]+\.[A-Za-z0-9._~!$&'()*+,;=:-]+$/i;
+
+/** Validate URI components without normalizing registry identities or treating them as URLs. */
+export const resourceUri = z.string().refine((value) => {
+  const parts =
+    /^[A-Za-z][A-Za-z0-9+.-]*:(?:\/\/([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#([^#]*))?$/.exec(
+      value,
+    );
+  if (
+    !parts ||
+    !path.test(parts[2] ?? "") ||
+    !queryOrFragment.test(parts[3] ?? "") ||
+    !queryOrFragment.test(parts[4] ?? "")
+  )
+    return false;
+  if (parts[1] === undefined) return true;
+  const host = authority.exec(parts[1]);
+  if (!host) return false;
+  const ip = host[1];
+  return (
+    ip === undefined || ipFuture.test(ip) || URL.canParse(`https://[${ip}]/`)
+  );
+}, "Resource URI must be an absolute URI");
+
+export const resourceMetadata = z.strictObject({
+  uri: resourceUri,
+  name: z.string().min(1),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  mimeType: z.string().optional(),
+  annotations: z
+    .looseObject({
+      audience: z.array(z.enum(["user", "assistant"])).optional(),
+      priority: z.number().min(0).max(1).optional(),
+      lastModified: z.string().optional(),
+    })
+    .optional(),
+  size: z.number().int().nonnegative().optional(),
+  icons: z.array(icon).optional(),
+  _meta: object.optional(),
+});
+
+const contents = z
+  .looseObject({
+    uri: resourceUri,
+    mimeType: z.string().optional(),
+    text: z.string().optional(),
+    blob: z.base64().optional(),
+    _meta: object.optional(),
+  })
+  .refine(
+    (value) => Object.hasOwn(value, "text") !== Object.hasOwn(value, "blob"),
+    "Resource contents require exactly one of text or blob",
+  );
+const readResult = z.strictObject({
+  contents: z.array(contents),
+  _meta: object.optional(),
+});
+
+export function copyReadResult(value: unknown): ResourceExecutionResult {
+  assertJSON(value, { omitUndefined: true });
+  return readResult.parse(
+    JSON.parse(JSON.stringify(value)),
+  ) as ResourceExecutionResult;
+}

package/src/server.ts

@@ -15,6 +15,8 @@ import { type ErrorHandler, reportError } from "./diagnostics.js";
 import { createDispatcher, formatErrorResponse } from "./dispatcher.js";
 import { executeRequest } from "./execute-request.js";
 import { decode } from "./protocol/decode.js";
+import type { Resource } from "./resources/definition.js";
+import { createResourceRegistry } from "./resources/registry.js";
 import { createToolAdapter } from "./tools/adapter.js";
 import type { ToolMap } from "./tools/registry.js";
 import {
@@ -30,7 +32,7 @@ interface ResponseDeliveryOptions {
   [responseDelivery]?: (response: ProtocolResponse) => void | Promise<void>;
 }
 
-/** Tool registrations, identity, and shared configuration for an MCP server. */
+/** Tool/resource registrations, identity, and shared configuration for an MCP server. */
 export interface ServerOptions<Tools extends ToolMap = ToolMap> {
   /** Server implementation name advertised to clients. */
   name: string;
@@ -38,12 +40,14 @@ export interface ServerOptions<Tools extends ToolMap = ToolMap> {
   version: string;
   /** Tools made with `tool()`; each registration key becomes its exposed tool name. */
   tools: Tools;
+  /** Fixed resources made with `resource()`; supplying an empty array enables an empty resource service. */
+  resources?: readonly Resource[];
   /** Optional usage instructions advertised to clients during discovery or initialization. */
   instructions?: string;
   /**
    * Receives original unexpected failures for private diagnostics. Tool failures
    * include frozen tool/request details; auth and transport failures pass only
-   * the error. Throws and rejected promises from this callback are ignored.
+   * the error, as do resource failures. Throws and rejected promises from this callback are ignored.
    */
   onError?: ErrorHandler;
   /** Eager endpoint authorization; requires a request transport rather than stdio. */
@@ -122,8 +126,8 @@ export interface Server {
 }
 
 /**
- * Create a server from reusable tools, optional auth, and lazy context providers.
- * Registration validates tool names, metadata, and exposable schemas immediately.
+ * Create a server from reusable tools/resources, optional auth, and lazy context providers.
+ * Registration validates tool names/schemas, resource URIs, and metadata immediately.
  * Creating the server does not start a transport or resolve context providers.
  *
  * @param options - Server identity and application-owned tool/provider registrations.
@@ -140,6 +144,9 @@ export function createServer<const Tools extends ToolMap>(
     { name: options.name, version: options.version },
     options.instructions,
     createContextRegistry(options.context),
+    options.resources === undefined
+      ? undefined
+      : createResourceRegistry(options.resources, options.onError),
   );
   let closed = false;
   const running = new Set<AbortController>();

package/src/tools/context.ts

@@ -42,7 +42,7 @@ export interface ToolRequest {
   readonly meta: Readonly<Record<string, unknown>>;
 }
 
-/** Per-invocation data passed to tool handlers and lazy context resolvers. */
+/** Per-invocation data passed to tool handlers, resource readers, and lazy context resolvers. */
 export interface ToolContext {
   /** Aborts when the client cancels or disconnects, or the transport or server closes. */
   readonly signal: AbortSignal;
@@ -70,7 +70,7 @@ export interface ToolContextOptions {
 }
 
 /**
- * Build an unauthenticated context for direct `execute()` calls, for example in tests.
+ * Build an unauthenticated context for direct tool `execute()` or resource `read()` calls.
  * Request metadata is copied and deeply frozen; each call creates a fresh provider cache.
  * Direct execution still bypasses server authorization, validation, and MCP conversion.
  *