mcp-server-framework 1.0.0

package/build/mcp/capabilities/tasks/define-task.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Task Tool Definition Factory
+ *
+ * Provides the defineTask() factory function for defining MCP task tools.
+ * Task tools enable long-running, asynchronous tool execution with a
+ * create → poll → result lifecycle.
+ *
+ * Tools defined with this function are automatically registered in the
+ * global task tool registry and discovered by `createServer()`.
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ * @module mcp/capabilities/tasks/define-task
+ */
+import type { z } from "zod";
+import type { TaskToolDefinition } from "../../types/index.js";
+/**
+ * Define a task tool with automatic registration.
+ *
+ * Task tools support long-running operations via the MCP Tasks protocol.
+ * Instead of blocking until completion, the client receives a task ID and
+ * can poll for status updates and results.
+ *
+ * The tool is automatically registered in the global task tool registry.
+ * The framework uses the SDK's `experimental.tasks.registerToolTask()` internally.
+ *
+ * @typeParam TInput - Zod schema type (inferred)
+ *
+ * @param definition - Task tool definition with name, description, input schema, and task handler
+ * @returns The registered task tool definition (for re-export and type inference)
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ *
+ * @example
+ * ```typescript
+ * import { defineTask, text, z } from 'mcp-server-framework';
+ *
+ * export const longComputation = defineTask({
+ *   name: 'long_computation',
+ *   description: 'Perform a long-running computation',
+ *   input: z.object({ data: z.string() }),
+ *   taskSupport: 'required',
+ *   taskHandler: {
+ *     createTask: async (args, ctx) => {
+ *       const task = await ctx.taskStore.createTask({ ttl: 300_000 });
+ *       startBackgroundWork(task.taskId, args);
+ *       return { task };
+ *     },
+ *     getTask: async (_args, ctx) => ctx.taskStore.getTask(ctx.taskId),
+ *     getTaskResult: async (_args, ctx) => ctx.taskStore.getTaskResult(ctx.taskId),
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Optional task support — tool can be called normally OR as a task
+ * export const flexibleTool = defineTask({
+ *   name: 'flexible_process',
+ *   description: 'Process that supports both sync and async execution',
+ *   input: z.object({ items: z.array(z.string()) }),
+ *   taskSupport: 'optional',
+ *   taskHandler: {
+ *     createTask: async (args, ctx) => {
+ *       const task = await ctx.taskStore.createTask({});
+ *       processInBackground(task.taskId, args);
+ *       return { task };
+ *     },
+ *     getTask: async (_args, ctx) => ctx.taskStore.getTask(ctx.taskId),
+ *     getTaskResult: async (_args, ctx) => ctx.taskStore.getTaskResult(ctx.taskId),
+ *   },
+ * });
+ * ```
+ */
+export declare function defineTask<TInput extends z.ZodTypeAny>(definition: TaskToolDefinition<TInput>): TaskToolDefinition<TInput>;
+//# sourceMappingURL=define-task.d.ts.map

package/build/mcp/capabilities/tasks/define-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-task.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/tasks/define-task.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAc/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EACpD,UAAU,EAAE,kBAAkB,CAAC,MAAM,CAAC,GACrC,kBAAkB,CAAC,MAAM,CAAC,CAmB5B"}

package/build/mcp/capabilities/tasks/define-task.js

@@ -0,0 +1,93 @@
+/**
+ * Task Tool Definition Factory
+ *
+ * Provides the defineTask() factory function for defining MCP task tools.
+ * Task tools enable long-running, asynchronous tool execution with a
+ * create → poll → result lifecycle.
+ *
+ * Tools defined with this function are automatically registered in the
+ * global task tool registry and discovered by `createServer()`.
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ * @module mcp/capabilities/tasks/define-task
+ */
+import { globalTaskToolRegistry } from "../registry/index.js";
+import { validateDefinitionBase, validateFunction, validateZodSchema, validateObject, validateEnum, } from "../../../utils/index.js";
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Define a task tool with automatic registration.
+ *
+ * Task tools support long-running operations via the MCP Tasks protocol.
+ * Instead of blocking until completion, the client receives a task ID and
+ * can poll for status updates and results.
+ *
+ * The tool is automatically registered in the global task tool registry.
+ * The framework uses the SDK's `experimental.tasks.registerToolTask()` internally.
+ *
+ * @typeParam TInput - Zod schema type (inferred)
+ *
+ * @param definition - Task tool definition with name, description, input schema, and task handler
+ * @returns The registered task tool definition (for re-export and type inference)
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ *
+ * @example
+ * ```typescript
+ * import { defineTask, text, z } from 'mcp-server-framework';
+ *
+ * export const longComputation = defineTask({
+ *   name: 'long_computation',
+ *   description: 'Perform a long-running computation',
+ *   input: z.object({ data: z.string() }),
+ *   taskSupport: 'required',
+ *   taskHandler: {
+ *     createTask: async (args, ctx) => {
+ *       const task = await ctx.taskStore.createTask({ ttl: 300_000 });
+ *       startBackgroundWork(task.taskId, args);
+ *       return { task };
+ *     },
+ *     getTask: async (_args, ctx) => ctx.taskStore.getTask(ctx.taskId),
+ *     getTaskResult: async (_args, ctx) => ctx.taskStore.getTaskResult(ctx.taskId),
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Optional task support — tool can be called normally OR as a task
+ * export const flexibleTool = defineTask({
+ *   name: 'flexible_process',
+ *   description: 'Process that supports both sync and async execution',
+ *   input: z.object({ items: z.array(z.string()) }),
+ *   taskSupport: 'optional',
+ *   taskHandler: {
+ *     createTask: async (args, ctx) => {
+ *       const task = await ctx.taskStore.createTask({});
+ *       processInBackground(task.taskId, args);
+ *       return { task };
+ *     },
+ *     getTask: async (_args, ctx) => ctx.taskStore.getTask(ctx.taskId),
+ *     getTaskResult: async (_args, ctx) => ctx.taskStore.getTaskResult(ctx.taskId),
+ *   },
+ * });
+ * ```
+ */
+export function defineTask(definition) {
+    // Validate required fields
+    validateDefinitionBase(definition, "TaskTool");
+    validateZodSchema(definition.input, "TaskTool", "input");
+    // Validate task handler object and its methods
+    validateObject(definition.taskHandler, "TaskTool", "taskHandler");
+    validateFunction(definition.taskHandler.createTask, "TaskTool", "taskHandler.createTask");
+    validateFunction(definition.taskHandler.getTask, "TaskTool", "taskHandler.getTask");
+    validateFunction(definition.taskHandler.getTaskResult, "TaskTool", "taskHandler.getTaskResult");
+    // Validate taskSupport value (defaults to 'required')
+    const taskSupport = definition.taskSupport ?? "required";
+    validateEnum(taskSupport, ["optional", "required"], "TaskTool", "taskSupport");
+    // Auto-register in global task tool registry
+    globalTaskToolRegistry.registerFromFactory(definition);
+    return definition;
+}
+//# sourceMappingURL=define-task.js.map

package/build/mcp/capabilities/tasks/define-task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-task.js","sourceRoot":"","sources":["../../../../src/mcp/capabilities/tasks/define-task.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,YAAY,GACb,MAAM,yBAAyB,CAAC;AAEjC,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,MAAM,UAAU,UAAU,CACxB,UAAsC;IAEtC,2BAA2B;IAC3B,sBAAsB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAC/C,iBAAiB,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAEzD,+CAA+C;IAC/C,cAAc,CAAC,UAAU,CAAC,WAAW,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;IAClE,gBAAgB,CAAC,UAAU,CAAC,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,wBAAwB,CAAC,CAAC;IAC1F,gBAAgB,CAAC,UAAU,CAAC,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,qBAAqB,CAAC,CAAC;IACpF,gBAAgB,CAAC,UAAU,CAAC,WAAW,CAAC,aAAa,EAAE,UAAU,EAAE,2BAA2B,CAAC,CAAC;IAEhG,sDAAsD;IACtD,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,IAAI,UAAU,CAAC;IACzD,YAAY,CAAC,WAAW,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;IAE/E,6CAA6C;IAC7C,sBAAsB,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAEvD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/build/mcp/capabilities/tasks/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Task Tools Module
+ *
+ * Provides the defineTask() factory for creating MCP task tools
+ * (tools with asynchronous execution support).
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ * @module mcp/capabilities/tasks
+ */
+export { defineTask } from "./define-task.js";
+//# sourceMappingURL=index.d.ts.map

package/build/mcp/capabilities/tasks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/tasks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/build/mcp/capabilities/tasks/index.js

@@ -0,0 +1,11 @@
+/**
+ * MCP Task Tools Module
+ *
+ * Provides the defineTask() factory for creating MCP task tools
+ * (tools with asynchronous execution support).
+ *
+ * @experimental MCP Tasks is an experimental SDK feature
+ * @module mcp/capabilities/tasks
+ */
+export { defineTask } from "./define-task.js";
+//# sourceMappingURL=index.js.map

package/build/mcp/capabilities/tasks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp/capabilities/tasks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/build/mcp/capabilities/tools/define-tool.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tool Definition Factory
+ *
+ * Provides the defineTool() factory function for zero-boilerplate tool registration.
+ * Tools defined with this function are automatically registered in a global registry.
+ *
+ * @module mcp/capabilities/tools/define-tool
+ */
+import type { z } from "zod";
+import type { ToolDefinition } from "../../types/index.js";
+/**
+ * Define a tool with automatic registration.
+ *
+ * This is the recommended way to define tools in the framework.
+ * The tool is automatically registered in the global registry when defined.
+ *
+ * @typeParam TInput - Zod schema type (inferred)
+ *
+ * @param definition - Tool definition with name, description, input schema, and handler
+ * @returns The registered tool definition (for re-export and type inference)
+ *
+ * **Important**: Call `defineTool()` at module scope (top-level). The tool is
+ * registered as a side-effect of module import. For conditional or runtime
+ * tool management, use `McpServerBuilder` with a custom `ToolProvider`.
+ *
+ * @example
+ * ```typescript
+ * // tools/greet.ts
+ * import { defineTool, text } from 'mcp-server-framework';
+ * import { z } from 'zod';
+ *
+ * export const greetTool = defineTool({
+ *   name: 'greet',
+ *   description: 'Greet a user by name',
+ *   input: z.object({
+ *     name: z.string().describe('The name to greet'),
+ *   }),
+ *   handler: async ({ name }) => text(`Hello, ${name}!`),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // tools/items.ts - With annotations and external API client
+ * import { defineTool, json } from 'mcp-server-framework';
+ * import { z } from 'zod';
+ * import { apiClient } from '../api/client.js';
+ *
+ * export const listItems = defineTool({
+ *   name: 'list_items',
+ *   description: 'List all items',
+ *   input: z.object({ category: z.string() }),
+ *   annotations: { readOnlyHint: true, openWorldHint: true },
+ *   handler: async ({ category }) => {
+ *     const items = await apiClient.items.list(category);
+ *     return json(items);
+ *   },
+ * });
+ * ```
+ */
+export declare function defineTool<TInput extends z.ZodTypeAny>(definition: ToolDefinition<TInput>): ToolDefinition<TInput>;
+//# sourceMappingURL=define-tool.d.ts.map

package/build/mcp/capabilities/tools/define-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/tools/define-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQ3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,CAUlH"}

package/build/mcp/capabilities/tools/define-tool.js

@@ -0,0 +1,73 @@
+/**
+ * Tool Definition Factory
+ *
+ * Provides the defineTool() factory function for zero-boilerplate tool registration.
+ * Tools defined with this function are automatically registered in a global registry.
+ *
+ * @module mcp/capabilities/tools/define-tool
+ */
+import { globalToolRegistry } from "../registry/index.js";
+import { validateDefinitionBase, validateFunction, validateZodSchema } from "../../../utils/index.js";
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Define a tool with automatic registration.
+ *
+ * This is the recommended way to define tools in the framework.
+ * The tool is automatically registered in the global registry when defined.
+ *
+ * @typeParam TInput - Zod schema type (inferred)
+ *
+ * @param definition - Tool definition with name, description, input schema, and handler
+ * @returns The registered tool definition (for re-export and type inference)
+ *
+ * **Important**: Call `defineTool()` at module scope (top-level). The tool is
+ * registered as a side-effect of module import. For conditional or runtime
+ * tool management, use `McpServerBuilder` with a custom `ToolProvider`.
+ *
+ * @example
+ * ```typescript
+ * // tools/greet.ts
+ * import { defineTool, text } from 'mcp-server-framework';
+ * import { z } from 'zod';
+ *
+ * export const greetTool = defineTool({
+ *   name: 'greet',
+ *   description: 'Greet a user by name',
+ *   input: z.object({
+ *     name: z.string().describe('The name to greet'),
+ *   }),
+ *   handler: async ({ name }) => text(`Hello, ${name}!`),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // tools/items.ts - With annotations and external API client
+ * import { defineTool, json } from 'mcp-server-framework';
+ * import { z } from 'zod';
+ * import { apiClient } from '../api/client.js';
+ *
+ * export const listItems = defineTool({
+ *   name: 'list_items',
+ *   description: 'List all items',
+ *   input: z.object({ category: z.string() }),
+ *   annotations: { readOnlyHint: true, openWorldHint: true },
+ *   handler: async ({ category }) => {
+ *     const items = await apiClient.items.list(category);
+ *     return json(items);
+ *   },
+ * });
+ * ```
+ */
+export function defineTool(definition) {
+    // Validate required fields (safety net for JS consumers and empty strings)
+    validateDefinitionBase(definition, "Tool");
+    validateZodSchema(definition.input, "Tool", "input");
+    validateFunction(definition.handler, "Tool", "handler");
+    // Auto-register in global registry (variance handled by registry)
+    globalToolRegistry.registerFromFactory(definition);
+    return definition;
+}
+//# sourceMappingURL=define-tool.js.map

package/build/mcp/capabilities/tools/define-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.js","sourceRoot":"","sources":["../../../../src/mcp/capabilities/tools/define-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEtG,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,UAAU,UAAU,CAA8B,UAAkC;IACxF,2EAA2E;IAC3E,sBAAsB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC3C,iBAAiB,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACrD,gBAAgB,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IAExD,kEAAkE;IAClE,kBAAkB,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAEnD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/build/mcp/capabilities/tools/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tools Module
+ *
+ * Exports the tool definition factory for zero-boilerplate registration.
+ * Types should be imported directly from `mcp/types/`.
+ *
+ * @module mcp/capabilities/tools
+ */
+export { defineTool } from "./define-tool.js";
+//# sourceMappingURL=index.d.ts.map

package/build/mcp/capabilities/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp/capabilities/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/build/mcp/capabilities/tools/index.js

@@ -0,0 +1,10 @@
+/**
+ * Tools Module
+ *
+ * Exports the tool definition factory for zero-boilerplate registration.
+ * Types should be imported directly from `mcp/types/`.
+ *
+ * @module mcp/capabilities/tools
+ */
+export { defineTool } from "./define-tool.js";
+//# sourceMappingURL=index.js.map

package/build/mcp/capabilities/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp/capabilities/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/build/mcp/handlers/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * MCP Protocol Handlers Module
+ *
+ * Setup functions for MCP protocol request/notification handlers.
+ *
+ * - **Ping Handler**: Responds to client liveness checks
+ * - **Progress Reporter**: Rate-limited progress notifications
+ *
+ * Cancellation is handled natively by the MCP SDK's Protocol layer.
+ * The SDK creates per-request AbortControllers and automatically aborts
+ * them when `notifications/cancelled` is received. No custom handler needed.
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation
+ * @module mcp/handlers
+ */
+export { setupPingHandler } from "./ping.js";
+export { createProgressReporter } from "./progress.js";
+//# sourceMappingURL=index.d.ts.map

package/build/mcp/handlers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAM7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC"}

package/build/mcp/handlers/index.js

@@ -0,0 +1,26 @@
+/**
+ * MCP Protocol Handlers Module
+ *
+ * Setup functions for MCP protocol request/notification handlers.
+ *
+ * - **Ping Handler**: Responds to client liveness checks
+ * - **Progress Reporter**: Rate-limited progress notifications
+ *
+ * Cancellation is handled natively by the MCP SDK's Protocol layer.
+ * The SDK creates per-request AbortControllers and automatically aborts
+ * them when `notifications/cancelled` is received. No custom handler needed.
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation
+ * @module mcp/handlers
+ */
+// ============================================================================
+// Handler Setup Functions
+// @internal Used by McpSession during initialization
+// ============================================================================
+export { setupPingHandler } from "./ping.js";
+// ============================================================================
+// Progress Utilities
+// ============================================================================
+export { createProgressReporter } from "./progress.js";
+//# sourceMappingURL=index.js.map

package/build/mcp/handlers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,+EAA+E;AAC/E,0BAA0B;AAC1B,qDAAqD;AACrD,+EAA+E;AAE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC"}

package/build/mcp/handlers/ping.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Ping Handler
+ *
+ * Handles ping/pong liveness checks per MCP Specification.
+ *
+ * Per MCP Spec:
+ * - Ping is a standard request that servers SHOULD respond to
+ * - Response is an empty object
+ * - Used for connection health checks
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping
+ * @module mcp/handlers/ping
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PingHandler } from "../types/index.js";
+/**
+ * Sets up the ping request handler.
+ *
+ * Registers a handler that responds to ping requests with an empty object
+ * and optionally invokes a custom handler for app-specific logic.
+ *
+ * @internal Called by McpSession during initialization.
+ * @param server - The McpServer instance
+ * @param onPing - Optional custom handler for app logic (metrics, health tracking, etc.)
+ */
+export declare function setupPingHandler(server: McpServer, onPing?: PingHandler): void;
+//# sourceMappingURL=ping.d.ts.map

package/build/mcp/handlers/ping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ping.d.ts","sourceRoot":"","sources":["../../../src/mcp/handlers/ping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAqBrD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAuB9E"}

package/build/mcp/handlers/ping.js

@@ -0,0 +1,61 @@
+/**
+ * Ping Handler
+ *
+ * Handles ping/pong liveness checks per MCP Specification.
+ *
+ * Per MCP Spec:
+ * - Ping is a standard request that servers SHOULD respond to
+ * - Response is an empty object
+ * - Used for connection health checks
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping
+ * @module mcp/handlers/ping
+ */
+import { PingRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { logger as baseLogger, mcpLogger } from "../../logger/index.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const LOG_COMPONENT = "ping";
+/** @internal Log messages used by the ping handler. */
+const LogMessages = {
+    PONG_SENT: "🏓 pong",
+    PING_RECEIVED: "Received ping, sent pong",
+    HANDLER_REGISTERED: "%s handler registered",
+};
+const logger = baseLogger.child({ component: LOG_COMPONENT });
+// ============================================================================
+// Handler Implementation
+// ============================================================================
+/**
+ * Sets up the ping request handler.
+ *
+ * Registers a handler that responds to ping requests with an empty object
+ * and optionally invokes a custom handler for app-specific logic.
+ *
+ * @internal Called by McpSession during initialization.
+ * @param server - The McpServer instance
+ * @param onPing - Optional custom handler for app logic (metrics, health tracking, etc.)
+ */
+export function setupPingHandler(server, onPing) {
+    server.server.setRequestHandler(PingRequestSchema, async () => {
+        // Call custom handler if defined (fire-and-forget, errors logged)
+        if (onPing) {
+            try {
+                await Promise.resolve(onPing());
+            }
+            catch (err) {
+                logger.warn("Custom ping handler error: %s", err instanceof Error ? err.message : String(err));
+            }
+        }
+        // Log pong via MCP notification (demonstrates server -> client communication)
+        mcpLogger.info(LogMessages.PONG_SENT).catch(() => {
+            // Ignore errors if client disconnected
+        });
+        logger.trace(LogMessages.PING_RECEIVED);
+        // Return empty object as per MCP spec
+        return {};
+    });
+    logger.trace(LogMessages.HANDLER_REGISTERED, LOG_COMPONENT);
+}
+//# sourceMappingURL=ping.js.map

package/build/mcp/handlers/ping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ping.js","sourceRoot":"","sources":["../../../src/mcp/handlers/ping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGxE,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,MAAM,aAAa,GAAG,MAAM,CAAC;AAE7B,uDAAuD;AACvD,MAAM,WAAW,GAAG;IAClB,SAAS,EAAE,SAAS;IACpB,aAAa,EAAE,0BAA0B;IACzC,kBAAkB,EAAE,uBAAuB;CACnC,CAAC;AAEX,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC;AAE9D,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiB,EAAE,MAAoB;IACtE,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,iBAAiB,EAAE,KAAK,IAAoC,EAAE;QAC5F,kEAAkE;QAClE,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YAClC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,IAAI,CAAC,+BAA+B,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YACjG,CAAC;QACH,CAAC;QAED,8EAA8E;QAC9E,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YAC/C,uCAAuC;QACzC,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;QAExC,sCAAsC;QACtC,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAC9D,CAAC"}

package/build/mcp/handlers/progress.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Progress Reporting Utility
+ *
+ * Creates rate-limited progress reporters using the SDK's native
+ * `sendNotification` from `RequestHandlerExtra`. This replaces
+ * the redundant RequestManager progress functionality.
+ *
+ * Rate-limiting prevents flooding the client with too many
+ * `notifications/progress` messages during tight loops.
+ *
+ * @see https://spec.modelcontextprotocol.io/specification/2025-11-25/server/utilities/progress/
+ * @module mcp/handlers/progress
+ */
+import type { ProgressReporter, SendNotificationFn, ProgressToken } from "../types/index.js";
+/**
+ * Minimum interval between progress notifications in milliseconds.
+ * Prevents flooding the client with updates during tight loops.
+ */
+export declare const PROGRESS_MIN_INTERVAL_MS = 100;
+/**
+ * Creates a rate-limited progress reporter for a tool invocation.
+ *
+ * Uses the SDK's native `sendNotification` to send `notifications/progress`
+ * messages. Applies rate-limiting (100ms minimum interval) to prevent
+ * flooding the client during tight loops.
+ *
+ * @param sendNotification - The SDK extra's `sendNotification` function
+ * @param progressToken - The progress token from `_meta.progressToken` (undefined = no progress requested)
+ * @returns A ProgressReporter function, or undefined if no progressToken was provided
+ *
+ * @example
+ * ```typescript
+ * // Inside SDK tool callback:
+ * const reporter = createProgressReporter(extra.sendNotification, extra._meta?.progressToken);
+ *
+ * // Use in tool handler:
+ * await reporter?.({ progress: 1, total: 10, message: 'Processing...' });
+ * ```
+ */
+export declare function createProgressReporter(sendNotification: SendNotificationFn, progressToken: ProgressToken | undefined): ProgressReporter | undefined;
+//# sourceMappingURL=progress.d.ts.map

package/build/mcp/handlers/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/mcp/handlers/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAgB,gBAAgB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAM3G;;;GAGG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAW5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,kBAAkB,EACpC,aAAa,EAAE,aAAa,GAAG,SAAS,GACvC,gBAAgB,GAAG,SAAS,CAiC9B"}