@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/mcp-server/resources/utils/newResourceDefinition.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview New-style resource definition types and `resource()` builder function.
+ * Uses the Phase 3 field names: `handler`, `params`, `format`, `auth`.
+ * Handler receives `(params, ctx)` instead of `(uri, params, context)`.
+ * @module src/mcp-server/resources/utils/newResourceDefinition
+ */
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { ListResourcesResult, ReadResourceResult, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { ZodObject, ZodRawShape, z } from 'zod';
+import type { Context } from '../../../context.js';
+import type { ResourceAnnotations } from '../../../mcp-server/resources/utils/resourceDefinition.js';
+export type { ResourceAnnotations };
+/** Extra context provided to list() handlers. */
+export type ListExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+/**
+ * New-style resource definition with simplified field names.
+ * Handler receives `(params, ctx)` — URI is available on `ctx.uri`.
+ */
+export interface NewResourceDefinition<TParams extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape> | undefined = undefined> {
+    /** Display/behavior hints. */
+    annotations?: ResourceAnnotations;
+    /** Required auth scopes. */
+    auth?: string[];
+    /** LLM-facing description. */
+    description: string;
+    /** Optional examples for discoverability. */
+    examples?: {
+        name: string;
+        uri: string;
+    }[];
+    /**
+     * Optional formatter mapping output to ReadResourceResult contents.
+     * If omitted, a default JSON formatter is used.
+     */
+    format?: (result: unknown, meta: {
+        uri: URL;
+        mimeType: string;
+    }) => ReadResourceResult['contents'];
+    /**
+     * The core handler function. Receives validated params and unified Context.
+     * URI is available on `ctx.uri`. Throw McpError on failure.
+     */
+    handler: (params: z.infer<TParams>, ctx: Context) => TOutput extends ZodObject<ZodRawShape> ? z.infer<TOutput> | Promise<z.infer<TOutput>> : unknown | Promise<unknown>;
+    /**
+     * Optional provider for resource discovery/listing.
+     */
+    list?: (extra: ListExtra) => ListResourcesResult | Promise<ListResourcesResult>;
+    /** Default MIME type for response content. */
+    mimeType?: string;
+    /** Programmatic unique name. Defaults to slugified URI template if omitted. */
+    name?: string;
+    /** Zod schema for output validation. */
+    output?: TOutput;
+    /** Zod schema for route/template params. All fields need `.describe()`. */
+    params?: TParams;
+    /** Human-readable title for UI display. */
+    title?: string;
+    /** URI template for resource registration (e.g., 'myscheme://{itemId}/data'). */
+    uriTemplate: string;
+}
+/** Type-erased union for mixed arrays. */
+export type AnyNewResourceDefinition = NewResourceDefinition<ZodObject<ZodRawShape>, ZodObject<ZodRawShape> | undefined>;
+/**
+ * Type guard: is this a new-style resource definition?
+ */
+export declare function isNewResourceDefinition(def: unknown): def is AnyNewResourceDefinition;
+/**
+ * Creates a new-style resource definition with the URI template as first argument.
+ *
+ * @example
+ * ```ts
+ * const myResource = resource('myscheme://{itemId}/data', {
+ *   description: 'Retrieve item data by ID.',
+ *   mimeType: 'application/json',
+ *   params: z.object({ itemId: z.string().describe('Item identifier') }),
+ *   async handler(params, ctx) {
+ *     ctx.log.debug('Fetching item', { itemId: params.itemId });
+ *     return { id: params.itemId, status: 'active' };
+ *   },
+ * });
+ * ```
+ */
+export declare function resource<TParams extends ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape> | undefined = undefined>(uriTemplate: string, options: Omit<NewResourceDefinition<TParams, TOutput>, 'uriTemplate'>): NewResourceDefinition<TParams, TOutput>;
+//# sourceMappingURL=newResourceDefinition.d.ts.map

package/dist/mcp-server/resources/utils/newResourceDefinition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"newResourceDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/newResourceDefinition.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/resources/utils/newResourceDefinition.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview New-style resource definition types and `resource()` builder function.
+ * Uses the Phase 3 field names: `handler`, `params`, `format`, `auth`.
+ * Handler receives `(params, ctx)` instead of `(uri, params, context)`.
+ * @module src/mcp-server/resources/utils/newResourceDefinition
+ */
+/**
+ * Type guard: is this a new-style resource definition?
+ */
+export function isNewResourceDefinition(def) {
+    return (def !== null &&
+        typeof def === 'object' &&
+        'handler' in def &&
+        typeof def.handler === 'function' &&
+        'uriTemplate' in def &&
+        !('logic' in def));
+}
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+/**
+ * Creates a new-style resource definition with the URI template as first argument.
+ *
+ * @example
+ * ```ts
+ * const myResource = resource('myscheme://{itemId}/data', {
+ *   description: 'Retrieve item data by ID.',
+ *   mimeType: 'application/json',
+ *   params: z.object({ itemId: z.string().describe('Item identifier') }),
+ *   async handler(params, ctx) {
+ *     ctx.log.debug('Fetching item', { itemId: params.itemId });
+ *     return { id: params.itemId, status: 'active' };
+ *   },
+ * });
+ * ```
+ */
+export function resource(uriTemplate, options) {
+    return { uriTemplate, ...options };
+}
+//# sourceMappingURL=newResourceDefinition.js.map

package/dist/mcp-server/resources/utils/newResourceDefinition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"newResourceDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/newResourceDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8EH;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,OAAO,CACL,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,SAAS,IAAI,GAAG;QAChB,OAAQ,GAA+B,CAAC,OAAO,KAAK,UAAU;QAC9D,aAAa,IAAI,GAAG;QACpB,CAAC,CAAC,OAAO,IAAI,GAAG,CAAC,CAClB,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CAItB,WAAmB,EACnB,OAAqE;IAErE,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CAAC;AACrC,CAAC"}

package/dist/mcp-server/resources/utils/newResourceHandlerFactory.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Handler factory for new-style resource definitions.
+ * Constructs Context (with `uri`), checks inline auth, validates params, formats response.
+ * @module src/mcp-server/resources/utils/newResourceHandlerFactory
+ */
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import type { ReadResourceResult, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { StorageService } from '../../../storage/core/StorageService.js';
+import type { Logger } from '../../../utils/internal/logger.js';
+import type { AnyNewResourceDefinition } from './newResourceDefinition.js';
+type SdkExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+/** Services required by the handler factory to construct Context. */
+export interface ResourceHandlerFactoryServices {
+    logger: Logger;
+    storage: StorageService;
+}
+/**
+ * Creates an MCP resource read handler from a new-style resource definition.
+ * The returned function is compatible with the MCP SDK's resource callback type.
+ *
+ * Responsibilities:
+ * - Creates RequestContext from SDK context (for tracing)
+ * - Creates unified Context with `ctx.uri` set
+ * - Checks inline `auth` scopes if defined
+ * - Validates params via Zod schema
+ * - Formats response via `format` or JSON default
+ * - Catches errors and re-throws for the SDK
+ */
+export declare function createNewResourceHandler(def: AnyNewResourceDefinition, services: ResourceHandlerFactoryServices): (uri: URL, variables: Variables, extra: SdkExtra) => Promise<ReadResourceResult>;
+export {};
+//# sourceMappingURL=newResourceHandlerFactory.d.ts.map

package/dist/mcp-server/resources/utils/newResourceHandlerFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"newResourceHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/newResourceHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iDAAiD,CAAC;AACjF,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAM5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAM3E,KAAK,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAOvE,qEAAqE;AACrE,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;CACzB;AAgDD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,wBAAwB,EAC7B,QAAQ,EAAE,8BAA8B,GACvC,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAyDlF"}

package/dist/mcp-server/resources/utils/newResourceHandlerFactory.js

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Handler factory for new-style resource definitions.
+ * Constructs Context (with `uri`), checks inline auth, validates params, formats response.
+ * @module src/mcp-server/resources/utils/newResourceHandlerFactory
+ */
+import { createContext } from '../../../context.js';
+import { withRequiredScopes } from '../../../mcp-server/transports/auth/lib/authUtils.js';
+import { ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
+import { requestContextService } from '../../../utils/internal/requestContext.js';
+// ---------------------------------------------------------------------------
+// Default formatter
+// ---------------------------------------------------------------------------
+function defaultResponseFormatter(result, meta) {
+    return [
+        {
+            uri: meta.uri.href,
+            text: JSON.stringify(result, null, 2),
+            mimeType: meta.mimeType,
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// Capability detection helpers
+// ---------------------------------------------------------------------------
+function wrapElicit(sdkContext) {
+    if (typeof sdkContext.elicitInput !== 'function')
+        return;
+    const fn = sdkContext.elicitInput;
+    return (msg, schema) => fn({ message: msg, requestedSchema: schema });
+}
+function wrapSample(sdkContext) {
+    if (typeof sdkContext.createMessage !== 'function')
+        return;
+    const fn = sdkContext.createMessage;
+    return (msgs, opts) => fn({ messages: msgs, ...opts });
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates an MCP resource read handler from a new-style resource definition.
+ * The returned function is compatible with the MCP SDK's resource callback type.
+ *
+ * Responsibilities:
+ * - Creates RequestContext from SDK context (for tracing)
+ * - Creates unified Context with `ctx.uri` set
+ * - Checks inline `auth` scopes if defined
+ * - Validates params via Zod schema
+ * - Formats response via `format` or JSON default
+ * - Catches errors and re-throws for the SDK
+ */
+export function createNewResourceHandler(def, services) {
+    const mimeType = def.mimeType ?? 'application/json';
+    const formatter = def.format ?? defaultResponseFormatter;
+    return async (uri, variables, callContext) => {
+        const sdkContext = callContext;
+        const sdkCaps = callContext;
+        const sessionId = typeof sdkContext?.sessionId === 'string' ? sdkContext.sessionId : undefined;
+        const appContext = requestContextService.createRequestContext({
+            parentContext: {
+                ...(typeof sdkContext?.requestId === 'string' ? { requestId: sdkContext.requestId } : {}),
+                ...(sessionId ? { sessionId } : {}),
+            },
+            operation: 'HandleResourceRead',
+            additionalContext: {
+                resourceName: def.name ?? def.uriTemplate,
+                resourceUri: uri.href,
+                sessionId,
+                inputParams: variables,
+            },
+        });
+        try {
+            // Check inline auth scopes
+            if (def.auth && def.auth.length > 0) {
+                withRequiredScopes(def.auth, appContext);
+            }
+            // Validate params via schema if defined
+            const validatedParams = def.params ? def.params.parse(variables) : variables;
+            // Construct Context with uri set
+            const ctx = createContext({
+                appContext,
+                logger: services.logger,
+                storage: services.storage,
+                signal: sdkContext.signal,
+                elicit: wrapElicit(sdkCaps),
+                sample: wrapSample(sdkCaps),
+                uri,
+            });
+            const result = await Promise.resolve(def.handler(validatedParams, ctx));
+            const contents = formatter(result, { uri, mimeType });
+            return { contents };
+        }
+        catch (error) {
+            // Re-throw for the SDK to catch (same pattern as legacy resource handler)
+            throw ErrorHandler.handleError(error, {
+                operation: `resource:${def.name ?? def.uriTemplate}:readHandler`,
+                context: appContext,
+                input: { uri: uri.href, variables },
+            });
+        }
+    };
+}
+//# sourceMappingURL=newResourceHandlerFactory.js.map

package/dist/mcp-server/resources/utils/newResourceHandlerFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"newResourceHandlerFactory.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/newResourceHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AAEnF,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AAE9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAoB3E,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,SAAS,wBAAwB,CAC/B,MAAe,EACf,IAAoC;IAEpC,OAAO;QACL;YACE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI;YAClB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YACrC,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E,SAAS,UAAU,CAAC,UAAkC;IACpD,IAAI,OAAO,UAAU,CAAC,WAAW,KAAK,UAAU;QAAE,OAAO;IACzD,MAAM,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC;IAClC,OAAO,CAAC,GAAW,EAAE,MAA8B,EAAE,EAAE,CACrD,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,CAE3C,CAAC;AACN,CAAC;AAED,SAAS,UAAU,CAAC,UAAkC;IACpD,IAAI,OAAO,UAAU,CAAC,aAAa,KAAK,UAAU;QAAE,OAAO;IAC3D,MAAM,EAAE,GAAG,UAAU,CAAC,aAAa,CAAC;IACpC,OAAO,CACL,IAA0E,EAC1E,IAAmB,EACnB,EAAE,CACF,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAE7B,CAAC;AACN,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CACtC,GAA6B,EAC7B,QAAwC;IAExC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,kBAAkB,CAAC;IACpD,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,IAAI,wBAAwB,CAAC;IAEzD,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,EAA+B,EAAE;QACxE,MAAM,UAAU,GAAG,WAAkC,CAAC;QACtD,MAAM,OAAO,GAAG,WAAgD,CAAC;QAEjE,MAAM,SAAS,GAAG,OAAO,UAAU,EAAE,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAE/F,MAAM,UAAU,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YAC5D,aAAa,EAAE;gBACb,GAAG,CAAC,OAAO,UAAU,EAAE,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzF,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACpC;YACD,SAAS,EAAE,oBAAoB;YAC/B,iBAAiB,EAAE;gBACjB,YAAY,EAAE,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW;gBACzC,WAAW,EAAE,GAAG,CAAC,IAAI;gBACrB,SAAS;gBACT,WAAW,EAAE,SAAS;aACvB;SACF,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,2BAA2B;YAC3B,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpC,kBAAkB,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YAC3C,CAAC;YAED,wCAAwC;YACxC,MAAM,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAE7E,iCAAiC;YACjC,MAAM,GAAG,GAAG,aAAa,CAAC;gBACxB,UAAU;gBACV,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,MAAM,EAAE,UAAU,CAAC,MAAM;gBACzB,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC;gBAC3B,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC;gBAC3B,GAAG;aACJ,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC,CAAC;YAExE,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;YACtD,OAAO,EAAE,QAAQ,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,0EAA0E;YAC1E,MAAM,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE;gBACpC,SAAS,EAAE,YAAY,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW,cAAc;gBAChE,OAAO,EAAE,UAAU;gBACnB,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE;aACpC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/mcp-server/resources/utils/resourceDefinition.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Defines the standard structure for a declarative resource definition.
+ * This mirrors the ToolDefinition pattern to provide a consistent, modern
+ * architecture for MCP resources, separating pure logic from handler concerns.
+ * @module src/mcp-server/resources/utils/resourceDefinition
+ */
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { ListResourcesResult, ReadResourceResult, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { ZodObject, ZodRawShape, z } from 'zod';
+import type { RequestContext } from '../../../utils/internal/requestContext.js';
+/**
+ * Optional annotations providing clients additional context about a resource.
+ * Mirrors the MCP SDK's Annotations type.
+ */
+export interface ResourceAnnotations {
+    /** Describes who the intended customer of this object or data is. */
+    audience?: ('user' | 'assistant')[];
+    /** The timestamp of the last modification, as an ISO 8601 string. */
+    lastModified?: string;
+    /** Describes how important this data is (0 = least, 1 = most). */
+    priority?: number;
+}
+/**
+ * Represents a complete, self-contained definition of an MCP resource.
+ */
+export interface ResourceDefinition<TParamsSchema extends ZodObject<ZodRawShape>, TOutputSchema extends ZodObject<ZodRawShape> | undefined = undefined> {
+    /** Optional display/behavior hints. */
+    annotations?: ResourceAnnotations;
+    /** A concise description of what the resource returns. */
+    description: string;
+    /** Optional examples to improve discoverability. */
+    examples?: {
+        name: string;
+        uri: string;
+    }[];
+    /**
+     * Optional provider for list results. If provided, it's used for resource discovery.
+     * The `extra` parameter provides access to request metadata including pagination cursor
+     * via `extra._meta?.cursor` or from the request params.
+     * Return value should conform to the MCP SDK's ListResourcesResult, which can include
+     * a `nextCursor` field for pagination support per MCP spec 2025-06-18.
+     *
+     * @param extra - Request handler context including signal, authInfo, sessionId, and request metadata
+     * @returns ListResourcesResult with resources array and optional nextCursor for pagination
+     *
+     * @example
+     * ```typescript
+     * import { extractCursor, paginateArray } from '../../../utils/pagination/pagination.js';
+     *
+     * list: (extra) => {
+     *   const allResources = [...]  // Your full resource list
+     *   const cursor = extractCursor(extra._meta);
+     *   const { items, nextCursor } = paginateArray(
+     *     allResources,
+     *     cursor,
+     *     50,   // defaultPageSize
+     *     1000, // maxPageSize
+     *     context
+     *   );
+     *   return {
+     *     resources: items,
+     *     ...(nextCursor && { nextCursor }),
+     *   };
+     * }
+     * ```
+     */
+    list?: (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => ListResourcesResult | Promise<ListResourcesResult>;
+    /**
+     * The pure, stateless core logic for the resource read operation.
+     * MUST NOT contain try/catch. Throw McpError on failure.
+     */
+    logic: (uri: URL, params: z.infer<TParamsSchema>, context: RequestContext) => TOutputSchema extends ZodObject<ZodRawShape> ? z.infer<TOutputSchema> | Promise<z.infer<TOutputSchema>> : unknown;
+    /** Default mime type for the response content. */
+    mimeType?: string;
+    /** The programmatic, unique name for the resource (e.g., 'echo-resource'). */
+    name: string;
+    /** Optional Zod schema describing the successful output payload. */
+    outputSchema?: TOutputSchema;
+    /** Zod schema validating the route/template params received by the handler. */
+    paramsSchema: TParamsSchema;
+    /**
+     * Optional formatter mapping the logic result into MCP ReadResourceResult.contents entries.
+     * If omitted, a default JSON formatter is applied using `mimeType`.
+     */
+    responseFormatter?: (result: unknown, meta: {
+        uri: URL;
+        mimeType: string;
+    }) => ReadResourceResult['contents'];
+    /** Optional, human-readable title for display in UIs. */
+    title?: string;
+    /** The URI template used to register the resource (e.g., 'echo://{message}'). */
+    uriTemplate: string;
+}
+//# sourceMappingURL=resourceDefinition.d.ts.map

package/dist/mcp-server/resources/utils/resourceDefinition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/resourceDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC;IACpC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CACjC,aAAa,SAAS,SAAS,CAAC,WAAW,CAAC,EAC5C,aAAa,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,GAAG,SAAS;IAEpE,uCAAuC;IACvC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,IAAI,CAAC,EAAE,CACL,KAAK,EAAE,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,KAC1D,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACxD;;;OAGG;IACH,KAAK,EAAE,CACL,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,EAC9B,OAAO,EAAE,cAAc,KACpB,aAAa,SAAS,SAAS,CAAC,WAAW,CAAC,GAC7C,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,GACxD,OAAO,CAAC;IACZ,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,+EAA+E;IAC/E,YAAY,EAAE,aAAa,CAAC;IAC5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAClB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE;QAAE,GAAG,EAAE,GAAG,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KACjC,kBAAkB,CAAC,UAAU,CAAC,CAAC;IACpC,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/mcp-server/resources/utils/resourceDefinition.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=resourceDefinition.js.map

package/dist/mcp-server/resources/utils/resourceDefinition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/resourceDefinition.ts"],"names":[],"mappings":""}

package/dist/mcp-server/resources/utils/resourceHandlerFactory.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview A factory for registering standardized MCP resources from definitions.
+ * Encapsulates context creation, error handling, and response formatting, keeping
+ * resource logic pure and stateless.
+ * @module src/mcp-server/resources/utils/resourceHandlerFactory
+ */
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZodObject, ZodRawShape } from 'zod';
+import type { ResourceDefinition } from '../../../mcp-server/resources/utils/resourceDefinition.js';
+/**
+ * Registers a single resource definition with the provided MCP server.
+ */
+export declare function registerResource<TParamsSchema extends ZodObject<ZodRawShape>, TOutputSchema extends ZodObject<ZodRawShape> | undefined = undefined>(server: McpServer, def: ResourceDefinition<TParamsSchema, TOutputSchema>): Promise<void>;
+//# sourceMappingURL=resourceHandlerFactory.d.ts.map

package/dist/mcp-server/resources/utils/resourceHandlerFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/resourceHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,KAAK,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AAE3F,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAK,MAAM,KAAK,CAAC;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AA8D7F;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,aAAa,SAAS,SAAS,CAAC,WAAW,CAAC,EAC5C,aAAa,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,GAAG,SAAS,EACpE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,kBAAkB,CAAC,aAAa,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFzF"}

package/dist/mcp-server/resources/utils/resourceHandlerFactory.js

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview A factory for registering standardized MCP resources from definitions.
+ * Encapsulates context creation, error handling, and response formatting, keeping
+ * resource logic pure and stateless.
+ * @module src/mcp-server/resources/utils/resourceHandlerFactory
+ */
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
+import { ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
+import { logger } from '../../../utils/internal/logger.js';
+import { requestContextService } from '../../../utils/internal/requestContext.js';
+function defaultResponseFormatter(result, meta) {
+    return [
+        {
+            uri: meta.uri.href,
+            text: JSON.stringify(result),
+            mimeType: meta.mimeType,
+        },
+    ];
+}
+function ensureResourceContents(contents, handlerContext, resourceName, uri) {
+    if (!Array.isArray(contents)) {
+        throw new McpError(JsonRpcErrorCode.InternalError, 'Resource formatter must return an array of contents.', {
+            requestId: handlerContext.requestId,
+            resourceName,
+            uri: uri.href,
+        });
+    }
+    // We perform a shallow validation here. A full Zod schema validation would be safer
+    // but might be too slow for every resource call. This is a pragmatic trade-off.
+    for (const item of contents) {
+        if (typeof item !== 'object' || item === null || !('uri' in item)) {
+            throw new McpError(JsonRpcErrorCode.InternalError, 'Invalid content block found in resource formatter output. Each item must be an object with a `uri` property.', {
+                requestId: handlerContext.requestId,
+                resourceName,
+                uri: uri.href,
+            });
+        }
+    }
+    return contents;
+}
+/**
+ * Registers a single resource definition with the provided MCP server.
+ */
+export async function registerResource(server, def) {
+    const resourceName = def.name;
+    const registrationContext = requestContextService.createRequestContext({
+        operation: 'RegisterResource',
+        additionalContext: { resourceName },
+    });
+    logger.info(`Registering resource: '${resourceName}'`, registrationContext);
+    await ErrorHandler.tryCatch(() => {
+        const template = new ResourceTemplate(def.uriTemplate, {
+            list: def.list,
+        });
+        const mimeType = def.mimeType ?? 'application/json';
+        const formatter = def.responseFormatter ?? defaultResponseFormatter;
+        const title = def.title ?? resourceName;
+        server.resource(resourceName, template, {
+            title,
+            description: def.description,
+            mimeType,
+            ...(def.examples && { examples: def.examples }),
+            ...(def.annotations && { annotations: def.annotations }),
+        }, async (uri, params, callContext) => {
+            const sessionId = typeof callContext?.sessionId === 'string' ? callContext.sessionId : undefined;
+            // Extract only plain-data fields from callContext — spreading the raw SDK
+            // object copies native objects (AbortSignal) that crash Pino serialization.
+            const handlerContext = requestContextService.createRequestContext({
+                parentContext: {
+                    ...(typeof callContext?.requestId === 'string'
+                        ? { requestId: callContext.requestId }
+                        : {}),
+                    ...(sessionId ? { sessionId } : {}),
+                },
+                operation: 'HandleResourceRead',
+                additionalContext: {
+                    resourceUri: uri.href,
+                    sessionId,
+                    inputParams: params,
+                },
+            });
+            try {
+                const parsedParams = def.paramsSchema.parse(params);
+                const responseData = (await def.logic(uri, parsedParams, handlerContext));
+                const rawContents = formatter(responseData, {
+                    uri,
+                    mimeType,
+                });
+                const contents = ensureResourceContents(rawContents, handlerContext, resourceName, uri);
+                const readResult = { contents };
+                return readResult;
+            }
+            catch (error) {
+                // Centralized handler re-throws the error for the SDK to catch
+                throw ErrorHandler.handleError(error, {
+                    operation: `resource:${resourceName}:readHandler`,
+                    context: handlerContext,
+                    input: { uri: uri.href, params },
+                });
+            }
+        });
+        logger.notice(`Resource '${resourceName}' registered successfully.`, registrationContext);
+    }, {
+        operation: `RegisteringResource_${resourceName}`,
+        context: registrationContext,
+        errorCode: JsonRpcErrorCode.InitializationFailed,
+        critical: true,
+    });
+}
+//# sourceMappingURL=resourceHandlerFactory.js.map

package/dist/mcp-server/resources/utils/resourceHandlerFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceHandlerFactory.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/utils/resourceHandlerFactory.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/roots/roots-registration.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Service for implementing MCP roots capability.
+ * Roots provide filesystem/workspace context awareness for the server.
+ *
+ * MCP Roots Specification:
+ * @see {@link https://modelcontextprotocol.io/specification/2025-06-18/basic/roots | MCP Roots}
+ * @module src/mcp-server/roots/roots-registration
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { logger as defaultLogger } from '../../utils/internal/logger.js';
+export declare class RootsRegistry {
+    private logger;
+    constructor(logger: typeof defaultLogger);
+    /**
+     * Registers roots handlers on the given MCP server.
+     * Note: In MCP, roots are typically provided BY THE CLIENT to the server.
+     * This implementation provides a placeholder for demonstration.
+     * In production, roots would be received from the client via client.listRoots().
+     */
+    registerAll(_server: McpServer): void;
+}
+//# sourceMappingURL=roots-registration.d.ts.map

package/dist/mcp-server/roots/roots-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roots-registration.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/roots/roots-registration.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG1E,qBAAa,aAAa;IACZ,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,OAAO,aAAa;IAEhD;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI;CActC"}

package/dist/mcp-server/roots/roots-registration.js

@@ -0,0 +1,25 @@
+import { requestContextService } from '../../utils/internal/requestContext.js';
+export class RootsRegistry {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Registers roots handlers on the given MCP server.
+     * Note: In MCP, roots are typically provided BY THE CLIENT to the server.
+     * This implementation provides a placeholder for demonstration.
+     * In production, roots would be received from the client via client.listRoots().
+     */
+    registerAll(_server) {
+        const context = requestContextService.createRequestContext({
+            operation: 'RootsRegistry.registerAll',
+        });
+        this.logger.debug('Roots capability enabled (client-provided roots)', context);
+        // Note: The MCP SDK handles roots automatically via the client-server protocol.
+        // Servers receive roots from clients, not the other way around.
+        // This is just a placeholder to demonstrate the capability is enabled.
+        // To access roots in your tools, use sdkContext to query the client.
+        this.logger.info('Roots capability registered successfully', context);
+    }
+}
+//# sourceMappingURL=roots-registration.js.map

package/dist/mcp-server/roots/roots-registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roots-registration.js","sourceRoot":"","sources":["../../../src/mcp-server/roots/roots-registration.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAE3E,MAAM,OAAO,aAAa;IACJ;IAApB,YAAoB,MAA4B;QAA5B,WAAM,GAAN,MAAM,CAAsB;IAAG,CAAC;IAEpD;;;;;OAKG;IACH,WAAW,CAAC,OAAkB;QAC5B,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,2BAA2B;SACvC,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,kDAAkD,EAAE,OAAO,CAAC,CAAC;QAE/E,gFAAgF;QAChF,gEAAgE;QAChE,uEAAuE;QACvE,qEAAqE;QAErE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0CAA0C,EAAE,OAAO,CAAC,CAAC;IACxE,CAAC;CACF"}

package/dist/mcp-server/server.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Factory for creating configured MCP server instances.
+ * Creates an McpServer with identity, capabilities, and registered
+ * tools/resources/prompts/roots from the provided registries.
+ *
+ * MCP Specification References:
+ * - Lifecycle: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle
+ * - Overview (Capabilities): https://modelcontextprotocol.io/specification/2025-06-18/basic/index
+ * - Transports: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
+ * @module src/mcp-server/server
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AppConfig } from '../config/index.js';
+import type { PromptRegistry } from '../mcp-server/prompts/prompt-registration.js';
+import type { ResourceRegistry } from '../mcp-server/resources/resource-registration.js';
+import type { RootsRegistry } from '../mcp-server/roots/roots-registration.js';
+import type { ToolRegistry } from '../mcp-server/tools/tool-registration.js';
+/** Dependencies required to create an MCP server instance. */
+export interface McpServerDeps {
+    config: AppConfig;
+    promptRegistry: PromptRegistry;
+    resourceRegistry: ResourceRegistry;
+    rootsRegistry: RootsRegistry;
+    toolRegistry: ToolRegistry;
+}
+/**
+ * Creates and configures a new instance of the `McpServer`.
+ * Registries are provided directly — no DI container resolution.
+ *
+ * @returns A promise resolving with the configured `McpServer` instance.
+ * @throws {McpError} If any resource or tool registration fails.
+ */
+export declare function createMcpServerInstance(deps: McpServerDeps): Promise<McpServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp-server/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp-server/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iDAAiD,CAAC;AACxF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0CAA0C,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAI5E,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,SAAS,CAAC;IAClB,cAAc,EAAE,cAAc,CAAC;IAC/B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,aAAa,EAAE,aAAa,CAAC;IAC7B,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAmDrF"}