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

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;
@@ -50,8 +50,9 @@ export interface ToolContext {
   readonly request: ToolRequest;
   /**
    * Report request-scoped progress; safe to pass to helpers without binding.
-   * Await delivery/backpressure. Resolves without sending when no progress token
-   * or delivery channel exists, or after cancellation/completion. Active updates
+   * 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.
    */
@@ -69,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.
  *

package/src/tools/progress.ts

@@ -18,20 +18,45 @@ const update = z.object({
   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(
-  signal: AbortSignal,
+  requestSignal: AbortSignal,
   token: unknown,
   send?: (message: ProgressNotification) => void | Promise<void>,
 ) {
-  const validToken =
-    typeof token === "string" ||
-    (typeof token === "number" &&
-      Number.isFinite(token) &&
-      Number.isInteger(token));
+  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();
@@ -56,13 +81,23 @@ export function createProgressReporter(
       },
     };
     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) return send(message);
+            if (!signal.aborted) {
+              lastSent = performance.now();
+              return send(message);
+            }
           }),
           signal,
         );
+      }
     });
     // The awaiting handler observes failures; keep the queue usable for cleanup.
     writes = write.catch(() => {});
@@ -76,6 +111,9 @@ export function createProgressReporter(
     },
     close() {
       open = false;
+      lifetime.abort(
+        new DOMException("Progress reporting closed", "AbortError"),
+      );
     },
   };
 }

package/src/tools/rich-result.ts

@@ -2,7 +2,10 @@ 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. */
@@ -10,7 +13,7 @@ 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;
 }
 
 // Registered symbols let duplicate package copies recognize each other's results.
@@ -20,10 +23,10 @@ const RESULT_BRAND = Symbol.for("@toolgrain/mcp/result@1");
  * 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 class McpResult<Structured> {
+export class McpResult<Structured, Meta extends MetaObject = MetaObject> {
   constructor(
     /** Explicit MCP result envelope, before server validation and revision-specific conversion. */
-    readonly value: McpResultOptions<Structured>,
+    readonly value: McpResultOptions<Structured, Meta>,
   ) {
     Object.freeze(this);
   }
@@ -45,18 +48,24 @@ export 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;
   };
@@ -68,53 +77,68 @@ 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 function mcpResult<Structured = never>(
-  value: McpResultOptions<Structured> & {
+export 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 function mcpResult(
-  value: McpResultOptions<never> & {
+export 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 function mcpResult<Structured>(
-  value: McpResultOptions<Structured> & {
+export 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 function mcpResult<Structured>(
-  value: McpResultOptions<Structured> & {
+export 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 function mcpResult(value: McpResultOptions<never>): McpResult<never>;
+export 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.
@@ -122,11 +146,13 @@ export function mcpResult(value: McpResultOptions<never>): McpResult<never>;
  * @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 function mcpResult<Structured = never>(
-  value: McpResultOptions<Structured>,
-): McpResult<Structured>;
-export function mcpResult<Structured = never>(
-  value: McpResultOptions<Structured>,
-): McpResult<Structured> {
+export function mcpResult<
+  Structured = never,
+  const Meta extends MetaObject = MetaObject,
+>(value: McpResultOptions<Structured, Meta>): McpResult<Structured, Meta>;
+export function mcpResult<
+  Structured = never,
+  const Meta extends MetaObject = MetaObject,
+>(value: McpResultOptions<Structured, Meta>): McpResult<Structured, Meta> {
   return new McpResult(value);
 }