@ibm/ibmi-mcp-server 0.2.0 → 0.3.0

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

@@ -1,4 +1,15 @@
+/**
+ * Tool Registration Entry Point
+ *
+ * Registers all factory pattern tools with the MCP server.
+ * Each tool is registered directly using registerToolFromDefinition.
+ *
+ * @module tools
+ */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/** Registers all available tools with the MCP server. */
-export declare const registerAllTools: (server: McpServer) => Promise<void>;
+/**
+ * Registers all factory pattern tools with the MCP server.
+ * Tools are defined in the allToolDefinitions array.
+ */
+export declare function registerAllTools(server: McpServer): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQzE,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,GAAU,QAAQ,SAAS,KAAG,OAAO,CAAC,IAAI,CAStE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAUzE;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BvE"}

package/dist/mcp-server/tools/index.js

@@ -1,13 +1,33 @@
-import { requestContextService } from "../../utils/index.js";
+/**
+ * Tool Registration Entry Point
+ *
+ * Registers all factory pattern tools with the MCP server.
+ * Each tool is registered directly using registerToolFromDefinition.
+ *
+ * @module tools
+ */
+import { allToolDefinitions } from "../../ibmi-mcp-server/tools/index.js";
+import { registerToolFromDefinition } from "./utils/tool-factory.js";
+import { logger, requestContextService } from "../../utils/index.js";
 import { logOperationStart, logOperationSuccess, } from "../../utils/internal/logging-helpers.js";
-import { registerGenerateSqlTool } from "../../ibmi-mcp-server/tools/generateSql/index.js";
-/** Registers all available tools with the MCP server. */
-export const registerAllTools = async (server) => {
+import { config } from "../../config/index.js";
+/**
+ * Registers all factory pattern tools with the MCP server.
+ * Tools are defined in the allToolDefinitions array.
+ */
+export async function registerAllTools(server) {
     const context = requestContextService.createRequestContext({
-        operation: "registerAllTools",
+        operation: "RegisterAllTools",
     });
-    logOperationStart(context, "Starting registration of all tools...");
-    await Promise.all([registerGenerateSqlTool(server)]);
-    logOperationSuccess(context, "All tools have been registered successfully.");
-};
+    logOperationStart(context, `Registering ${allToolDefinitions.length} factory pattern tools`);
+    for (const toolDef of allToolDefinitions) {
+        if (toolDef.name === "execute_sql" && !config.ibmi_enableExecuteSql) {
+            // Skip execute_sql tool if disabled via IBMI_ENABLE_EXECUTE_SQL
+            logger.debug(context, "Skipping registration of execute_sql tool (IBMI_ENABLE_EXECUTE_SQL=false)");
+            continue;
+        }
+        await registerToolFromDefinition(server, toolDef);
+    }
+    logOperationSuccess(context, `Successfully registered ${allToolDefinitions.length} factory pattern tools`);
+}
 //# sourceMappingURL=index.js.map

package/dist/mcp-server/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAEvF,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,MAAiB,EAAiB,EAAE;IACzE,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;QACzD,SAAS,EAAE,kBAAkB;KAC9B,CAAC,CAAC;IACH,iBAAiB,CAAC,OAAO,EAAE,uCAAuC,CAAC,CAAC;IAEpE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAErD,mBAAmB,CAAC,OAAO,EAAE,8CAA8C,CAAC,CAAC;AAC/E,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAiB;IACtD,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;QACzD,SAAS,EAAE,kBAAkB;KAC9B,CAAC,CAAC;IAEH,iBAAiB,CACf,OAAO,EACP,eAAe,kBAAkB,CAAC,MAAM,wBAAwB,CACjE,CAAC;IAEF,KAAK,MAAM,OAAO,IAAI,kBAAkB,EAAE,CAAC;QACzC,IAAI,OAAO,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC;YACpE,gEAAgE;YAChE,MAAM,CAAC,KAAK,CACV,OAAO,EACP,2EAA2E,CAC5E,CAAC;YACF,SAAS;QACX,CAAC;QACD,MAAM,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,mBAAmB,CACjB,OAAO,EACP,2BAA2B,kBAAkB,CAAC,MAAM,wBAAwB,CAC7E,CAAC;AACJ,CAAC"}

package/dist/mcp-server/tools/utils/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tool utilities barrel file
+ * Exports tool-related utilities and types
+ */
+export type { ToolDefinition, ToolAnnotations, ToolLogicFn, SdkContext, } from "./types.js";
+export * from "./tool-factory.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/tools/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC;AAGpB,cAAc,mBAAmB,CAAC"}

package/dist/mcp-server/tools/utils/index.js

@@ -0,0 +1,7 @@
+/**
+ * Tool utilities barrel file
+ * Exports tool-related utilities and types
+ */
+// Export factory functions
+export * from "./tool-factory.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/tools/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,2BAA2B;AAC3B,cAAc,mBAAmB,CAAC"}

package/dist/mcp-server/tools/utils/tool-factory.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Tool Registration Factory
+ *
+ * Provides a factory pattern for creating and registering MCP tools with minimal boilerplate.
+ * Handles validation, registration, error handling, and response formatting automatically.
+ *
+ * @module tool-factory
+ * @feature 001-tool-factory
+ */
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type RequestContext } from "../../../utils/index.js";
+import type { ToolDefinition, ResponseFormatter, SdkContext } from "./types.js";
+/**
+ * Zod schema for validating tool definitions at registration time.
+ */
+export declare const ToolDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodType<z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>, z.ZodTypeDef, z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>>;
+    outputSchema: z.ZodType<z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>, z.ZodTypeDef, z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>>;
+    logic: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    title: z.ZodOptional<z.ZodString>;
+    responseFormatter: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>>;
+    annotations: z.ZodOptional<z.ZodObject<{
+        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+        destructiveHint: z.ZodOptional<z.ZodBoolean>;
+        openWorldHint: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        readOnlyHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+    }, {
+        readOnlyHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+    }>>;
+    enabled: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    outputSchema: z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    logic: (...args: unknown[]) => unknown;
+    enabled?: boolean | ((...args: unknown[]) => unknown) | undefined;
+    title?: string | undefined;
+    annotations?: {
+        readOnlyHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+    } | undefined;
+    responseFormatter?: ((...args: unknown[]) => unknown) | undefined;
+}, {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    outputSchema: z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny, {
+        [x: string]: any;
+    }, {
+        [x: string]: any;
+    }>;
+    logic: (...args: unknown[]) => unknown;
+    enabled?: boolean | ((...args: unknown[]) => unknown) | undefined;
+    title?: string | undefined;
+    annotations?: {
+        readOnlyHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+    } | undefined;
+    responseFormatter?: ((...args: unknown[]) => unknown) | undefined;
+}>;
+/**
+ * Creates a standardized MCP tool handler.
+ * This factory encapsulates context creation, performance measurement,
+ * error handling, and response formatting. It separates the app's internal
+ * RequestContext from the SDK's context (SdkContext).
+ *
+ * @param toolName - The name of the tool for logging and metrics
+ * @param logic - The core business logic function
+ * @param responseFormatter - Optional custom formatter (defaults to JSON)
+ * @returns A handler function compatible with the MCP SDK's tool callback
+ */
+export declare function createHandler<TInput, TOutput>(toolName: string, logic: (input: TInput, appContext: RequestContext, sdkContext: SdkContext) => Promise<TOutput>, responseFormatter?: ResponseFormatter<TOutput>): (input: TInput, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Factory function for creating tool definitions.
+ * Provides type inference and acts as the main entry point for tool authors.
+ *
+ * @param definition - The tool configuration
+ * @returns The same tool definition (for type inference)
+ */
+export declare function defineTool<TInputShape extends z.ZodRawShape, TOutputShape extends z.ZodRawShape>(definition: ToolDefinition<TInputShape, TOutputShape>): ToolDefinition<TInputShape, TOutputShape>;
+/**
+ * Registers a single tool from its definition.
+ * Accepts any tool definition shape to support arrays of mixed tool types.
+ *
+ * @param server - The MCP server instance
+ * @param toolDef - The tool definition to register
+ */
+export declare function registerToolFromDefinition(server: McpServer, toolDef: ToolDefinition<any, any>): Promise<void>;
+//# sourceMappingURL=tool-factory.d.ts.map

package/dist/mcp-server/tools/utils/tool-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-factory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/tool-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAa,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,cAAc,EAEf,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,KAAK,EACV,cAAc,EAEd,iBAAiB,EACjB,UAAU,EACX,MAAM,YAAY,CAAC;AAMpB;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgC/B,CAAC;AAkBH;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAC3C,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CACL,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,cAAc,EAC1B,UAAU,EAAE,UAAU,KACnB,OAAO,CAAC,OAAO,CAAC,EACrB,iBAAiB,GAAE,iBAAiB,CAAC,OAAO,CAA0D,GACrG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAiD5D;AAMD;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,WAAW,SAAS,CAAC,CAAC,WAAW,EACjC,YAAY,SAAS,CAAC,CAAC,WAAW,EAElC,UAAU,EAAE,cAAc,CAAC,WAAW,EAAE,YAAY,CAAC,GACpD,cAAc,CAAC,WAAW,EAAE,YAAY,CAAC,CAI3C;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,SAAS,EAEjB,OAAO,EAAE,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CA6Ef"}

package/dist/mcp-server/tools/utils/tool-factory.js

@@ -0,0 +1,179 @@
+/**
+ * Tool Registration Factory
+ *
+ * Provides a factory pattern for creating and registering MCP tools with minimal boilerplate.
+ * Handles validation, registration, error handling, and response formatting automatically.
+ *
+ * @module tool-factory
+ * @feature 001-tool-factory
+ */
+import { z } from "zod";
+import { JsonRpcErrorCode } from "../../../types-global/errors.js";
+import { ErrorHandler, requestContextService, measureToolExecution, } from "../../../utils/index.js";
+import { logOperationStart, logOperationSuccess, } from "../../../utils/internal/logging-helpers.js";
+// =============================================================================
+// Validation Schema
+// =============================================================================
+/**
+ * Zod schema for validating tool definitions at registration time.
+ */
+export const ToolDefinitionSchema = z.object({
+    name: z
+        .string()
+        .min(1, "Tool name is required")
+        .regex(/^[a-z][a-z0-9_]*$/, "Tool name must be snake_case (lowercase letters, numbers, underscores)"),
+    description: z.string().min(1, "Tool description is required"),
+    inputSchema: z.custom((val) => val instanceof z.ZodObject, {
+        message: "inputSchema must be a Zod object schema",
+    }),
+    outputSchema: z.custom((val) => val instanceof z.ZodObject, {
+        message: "outputSchema must be a Zod object schema",
+    }),
+    logic: z.function(),
+    title: z.string().optional(),
+    responseFormatter: z.function().optional(),
+    annotations: z
+        .object({
+        readOnlyHint: z.boolean().optional(),
+        destructiveHint: z.boolean().optional(),
+        openWorldHint: z.boolean().optional(),
+    })
+        .optional(),
+    enabled: z.union([z.boolean(), z.function()]).optional(),
+});
+// =============================================================================
+// Default Response Formatter
+// =============================================================================
+/**
+ * Default formatter for successful responses.
+ * Returns a simple JSON representation of the result.
+ */
+const defaultResponseFormatter = (result) => [
+    { type: "text", text: JSON.stringify(result, null, 2) },
+];
+// =============================================================================
+// Handler Factory
+// =============================================================================
+/**
+ * Creates a standardized MCP tool handler.
+ * This factory encapsulates context creation, performance measurement,
+ * error handling, and response formatting. It separates the app's internal
+ * RequestContext from the SDK's context (SdkContext).
+ *
+ * @param toolName - The name of the tool for logging and metrics
+ * @param logic - The core business logic function
+ * @param responseFormatter - Optional custom formatter (defaults to JSON)
+ * @returns A handler function compatible with the MCP SDK's tool callback
+ */
+export function createHandler(toolName, logic, responseFormatter = defaultResponseFormatter) {
+    return async (input, callContext) => {
+        // Cast the SDK context to our specific SdkContext type
+        const sdkContext = callContext;
+        const sessionId = typeof sdkContext?.sessionId === "string"
+            ? sdkContext.sessionId
+            : undefined;
+        // Create the application's internal logger/tracing context
+        const appContext = requestContextService.createRequestContext({
+            parentContext: sdkContext,
+            operation: "HandleToolRequest",
+            additionalContext: { toolName, sessionId, input },
+        });
+        try {
+            const result = await measureToolExecution(toolName, () => logic(input, appContext, sdkContext), input);
+            return {
+                structuredContent: result,
+                content: responseFormatter(result),
+            };
+        }
+        catch (error) {
+            const mcpError = ErrorHandler.handleError(error, {
+                operation: `tool:${toolName}`,
+                context: appContext,
+                input,
+            });
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: ${mcpError.message}` }],
+                structuredContent: {
+                    code: mcpError.code,
+                    message: mcpError.message,
+                    details: mcpError.details,
+                },
+            };
+        }
+    };
+}
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Factory function for creating tool definitions.
+ * Provides type inference and acts as the main entry point for tool authors.
+ *
+ * @param definition - The tool configuration
+ * @returns The same tool definition (for type inference)
+ */
+export function defineTool(definition) {
+    // Validate the definition
+    ToolDefinitionSchema.parse(definition);
+    return definition;
+}
+/**
+ * Registers a single tool from its definition.
+ * Accepts any tool definition shape to support arrays of mixed tool types.
+ *
+ * @param server - The MCP server instance
+ * @param toolDef - The tool definition to register
+ */
+export async function registerToolFromDefinition(server, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+toolDef) {
+    const registrationContext = requestContextService.createRequestContext({
+        operation: "RegisterTool",
+        toolName: toolDef.name,
+    });
+    logOperationStart(registrationContext, `Registering tool: '${toolDef.name}'`);
+    await ErrorHandler.tryCatch(async () => {
+        // Check if tool is enabled
+        const enabled = toolDef.enabled === undefined
+            ? true
+            : typeof toolDef.enabled === "function"
+                ? toolDef.enabled()
+                : toolDef.enabled;
+        if (!enabled) {
+            logOperationSuccess(registrationContext, `Tool '${toolDef.name}' is disabled, skipping registration`);
+            return;
+        }
+        // Prepare metadata
+        const title = toolDef.title ||
+            toolDef.name
+                .split("_")
+                .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+                .join(" ");
+        const annotations = {
+            readOnlyHint: toolDef.annotations?.readOnlyHint ?? false,
+            destructiveHint: toolDef.annotations?.destructiveHint ?? false,
+            openWorldHint: toolDef.annotations?.openWorldHint ?? false,
+        };
+        // Use custom formatter or default
+        const responseFormatter = toolDef.responseFormatter || defaultResponseFormatter;
+        // Create handler using the factory
+        const handler = createHandler(toolDef.name, toolDef.logic, responseFormatter);
+        // Register with MCP server
+        // Use .shape to extract raw schema like YAML tools do
+        server.registerTool(toolDef.name, {
+            title,
+            description: toolDef.description,
+            inputSchema: toolDef.inputSchema.shape,
+            outputSchema: toolDef.outputSchema.shape,
+            annotations,
+        }, handler);
+        logOperationSuccess(registrationContext, `Tool '${toolDef.name}' registered successfully`);
+    }, {
+        operation: `RegisteringTool_${toolDef.name}`,
+        context: registrationContext,
+        errorCode: JsonRpcErrorCode.InitializationFailed,
+        critical: true,
+    });
+}
+//# sourceMappingURL=tool-factory.js.map

package/dist/mcp-server/tools/utils/tool-factory.js.map

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

package/dist/mcp-server/tools/utils/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Tool Factory Contracts
+ *
+ * TypeScript interfaces defining the contract between tool authors
+ * and the registration system.
+ *
+ * @module tool-factory
+ * @feature 001-tool-factory
+ */
+import type { z, ZodObject, ZodRawShape } from "zod";
+import type { ContentBlock } from "@modelcontextprotocol/sdk/types.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { ServerNotification, ServerRequest } from "@modelcontextprotocol/sdk/types.js";
+import type { RequestContext } from "../../../utils/index.js";
+/**
+ * Defines the function signature for formatting a successful tool logic result
+ * into content blocks for display.
+ * @template TOutput The type of the successful output from the logic.
+ * @param result The successful output from the tool's logic function.
+ * @returns An array of ContentBlocks for the MCP client to display.
+ */
+export type ResponseFormatter<TOutput> = (result: TOutput) => ContentBlock[];
+/**
+ * A type alias for the SDK's `RequestHandlerExtra` context, making it more
+ * specific and easier to reference in our tool logic signatures.
+ * Provides access to protocol-level capabilities like cancellation, notifications, and auth.
+ */
+export type SdkContext = RequestHandlerExtra<ServerRequest, ServerNotification>;
+/**
+ * Function signature for tool business logic.
+ * Receives validated input, application context, and SDK context, returns structured output.
+ *
+ * @template TInput - Input type inferred from inputSchema
+ * @template TOutput - Output type inferred from outputSchema
+ */
+export type ToolLogicFn<TInput, TOutput> = (params: TInput, appContext: RequestContext, sdkContext: SdkContext) => Promise<TOutput>;
+/**
+ * MCP protocol hints for LLM decision-making.
+ * All fields are optional and default to false.
+ */
+export interface ToolAnnotations {
+    /** Tool only reads data, no side effects */
+    readOnlyHint?: boolean;
+    /** Tool may permanently delete or modify data */
+    destructiveHint?: boolean;
+    /** Tool makes external API or network calls */
+    openWorldHint?: boolean;
+}
+/**
+ * Developer-facing interface for declaring an MCP tool.
+ *
+ * @template TInputShape - Zod shape for input schema
+ * @template TOutputShape - Zod shape for output schema
+ *
+ * @example
+ * ```typescript
+ * const myTool = defineTool({
+ *   name: "my_tool",
+ *   description: "Does something useful",
+ *   inputSchema: z.object({ query: z.string() }),
+ *   outputSchema: z.object({ result: z.string() }),
+ *   logic: async ({ query }, appContext) => {
+ *     logger.debug({ ...appContext, query }, 'Processing query');
+ *     return { result: `Processed: ${query}` };
+ *   },
+ * });
+ * ```
+ */
+export interface ToolDefinition<TInputShape extends ZodRawShape = ZodRawShape, TOutputShape extends ZodRawShape = ZodRawShape> {
+    /**
+     * Unique tool identifier.
+     * Convention: snake_case (e.g., "describe_sql_object")
+     */
+    name: string;
+    /**
+     * LLM-facing description of tool capabilities.
+     * Should clearly explain what the tool does and when to use it.
+     */
+    description: string;
+    /**
+     * Zod schema validating tool input.
+     * Input is validated before logic function is called.
+     */
+    inputSchema: ZodObject<TInputShape>;
+    /**
+     * Zod schema defining expected output structure.
+     * Used for documentation and type inference.
+     */
+    outputSchema: ZodObject<TOutputShape>;
+    /**
+     * Pure async function implementing tool behavior.
+     * Receives validated input and application context, returns structured output.
+     */
+    logic: ToolLogicFn<z.infer<ZodObject<TInputShape>>, z.infer<ZodObject<TOutputShape>>>;
+    /**
+     * Human-readable title for UI display.
+     * Defaults to formatted tool name if not provided.
+     */
+    title?: string;
+    /**
+     * Custom output formatter.
+     * Defaults to JSON serialization with text summary.
+     */
+    responseFormatter?: ResponseFormatter<z.infer<ZodObject<TOutputShape>>>;
+    /**
+     * MCP safety hints for LLM decision-making.
+     * All hints default to false if not specified.
+     */
+    annotations?: ToolAnnotations;
+    /**
+     * Conditional registration control.
+     * Set to false or return false from function to skip registration.
+     * Defaults to true (tool is registered).
+     */
+    enabled?: boolean | (() => boolean);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp-server/tools/utils/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAM9D;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,KAAK,YAAY,EAAE,CAAC;AAE7E;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,EAAE,OAAO,IAAI,CACzC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,cAAc,EAC1B,UAAU,EAAE,UAAU,KACnB,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iDAAiD;IACjD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,+CAA+C;IAC/C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc,CAC7B,WAAW,SAAS,WAAW,GAAG,WAAW,EAC7C,YAAY,SAAS,WAAW,GAAG,WAAW;IAE9C;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,WAAW,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;IAEpC;;;OAGG;IACH,YAAY,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IAEtC;;;OAGG;IACH,KAAK,EAAE,WAAW,CAChB,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,EAC/B,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CACjC,CAAC;IAEF;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAExE;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAE9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;CACrC"}

package/dist/mcp-server/tools/utils/types.js

@@ -0,0 +1,11 @@
+/**
+ * Tool Factory Contracts
+ *
+ * TypeScript interfaces defining the contract between tool authors
+ * and the registration system.
+ *
+ * @module tool-factory
+ * @feature 001-tool-factory
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp-server/tools/utils/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/mcp-server/transports/core/cleanupTransformStream.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Creates a TransformStream wrapper that triggers cleanup when the stream completes.
+ *
+ * This utility wraps a ReadableStream with a transparent TransformStream that:
+ * - Passes through all chunks unchanged (identity transform)
+ * - Hooks into stream lifecycle events (flush, cancel, error)
+ * - Triggers cleanup automatically when the stream completes
+ * - Ensures cleanup happens exactly once
+ *
+ * @param originalStream - The ReadableStream to wrap
+ * @param onCleanup - Async function to call when the stream completes
+ * @returns A new ReadableStream that triggers cleanup on completion
+ *
+ * @example
+ * ```typescript
+ * const wrappedStream = createCleanupTransformStream(
+ *   responseStream,
+ *   async () => {
+ *     await server.close();
+ *     await transport.close();
+ *   }
+ * );
+ * ```
+ */
+export declare function createCleanupTransformStream(originalStream: ReadableStream, onCleanup: () => Promise<void>): ReadableStream;
+//# sourceMappingURL=cleanupTransformStream.d.ts.map

package/dist/mcp-server/transports/core/cleanupTransformStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanupTransformStream.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/transports/core/cleanupTransformStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,cAAc,EAC9B,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC7B,cAAc,CAuChB"}

package/dist/mcp-server/transports/core/cleanupTransformStream.js

@@ -0,0 +1,60 @@
+/**
+ * Creates a TransformStream wrapper that triggers cleanup when the stream completes.
+ *
+ * This utility wraps a ReadableStream with a transparent TransformStream that:
+ * - Passes through all chunks unchanged (identity transform)
+ * - Hooks into stream lifecycle events (flush, cancel, error)
+ * - Triggers cleanup automatically when the stream completes
+ * - Ensures cleanup happens exactly once
+ *
+ * @param originalStream - The ReadableStream to wrap
+ * @param onCleanup - Async function to call when the stream completes
+ * @returns A new ReadableStream that triggers cleanup on completion
+ *
+ * @example
+ * ```typescript
+ * const wrappedStream = createCleanupTransformStream(
+ *   responseStream,
+ *   async () => {
+ *     await server.close();
+ *     await transport.close();
+ *   }
+ * );
+ * ```
+ */
+export function createCleanupTransformStream(originalStream, onCleanup) {
+    // Track cleanup state to ensure idempotency
+    let cleanedUp = false;
+    const cleanup = async () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        await onCleanup();
+    };
+    // Create transform stream with lifecycle hooks
+    const { readable, writable } = new TransformStream({
+        /**
+         * Identity transform - passes chunks through unchanged
+         */
+        transform(chunk, controller) {
+            controller.enqueue(chunk);
+        },
+        /**
+         * Called when stream closes normally (all data consumed)
+         */
+        async flush() {
+            await cleanup();
+        },
+        /**
+         * Called when stream is cancelled/aborted by the consumer
+         */
+        async cancel() {
+            await cleanup();
+        },
+    });
+    // Pipe original stream through transform
+    // If piping fails (error in original stream), trigger cleanup
+    originalStream.pipeTo(writable).catch(() => cleanup());
+    return readable;
+}
+//# sourceMappingURL=cleanupTransformStream.js.map