@ibm/ibmi-mcp-server 0.1.0

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

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Defines the core types and interfaces for the transport layer abstraction.
+ * This module establishes the data contracts and abstract interfaces that decouple
+ * the MCP server's core logic from specific transport implementations like HTTP or stdio.
+ * @module src/mcp-server/transports/core/transportTypes
+ */
+import { RequestContext } from "../../../utils/index.js";
+import { McpTransportRequest } from "./transportRequest.js";
+/**
+ * Defines the set of valid HTTP status codes that the transport layer can return.
+ * This ensures type safety and consistency in response handling.
+ */
+export type HttpStatusCode = 200 | 201 | 400 | 401 | 403 | 404 | 409 | 429 | 500 | 502 | 503;
+/**
+ * A base interface for all transport responses, containing common properties.
+ */
+interface BaseTransportResponse {
+    sessionId?: string;
+    headers: Headers;
+    statusCode: HttpStatusCode;
+}
+/**
+ * Represents a transport response where the entire body is buffered in memory.
+ * Suitable for small, non-streamed responses.
+ */
+export interface BufferedTransportResponse extends BaseTransportResponse {
+    type: "buffered";
+    body: unknown;
+}
+/**
+ * Represents a transport response that streams its body.
+ * Essential for handling large or chunked responses efficiently without high memory usage.
+ */
+export interface StreamingTransportResponse extends BaseTransportResponse {
+    type: "stream";
+    stream: ReadableStream<Uint8Array>;
+}
+/**
+ * A discriminated union representing the possible types of a transport response.
+ * Using a discriminated union on the `type` property allows for type-safe handling
+ * of different response formats (buffered vs. streamed).
+ */
+export type TransportResponse = BufferedTransportResponse | StreamingTransportResponse;
+/**
+ * Defines the lifecycle states of a transport session.
+ */
+export declare enum SessionState {
+    ACTIVE = "ACTIVE",
+    CLOSING = "CLOSING"
+}
+/**
+ * Represents the state of an active, persistent transport session.
+ */
+export interface TransportSession {
+    id: string;
+    state: SessionState;
+    createdAt: Date;
+    lastAccessedAt: Date;
+    /**
+     * A counter for requests currently being processed for this session.
+     * This is a critical mechanism to prevent race conditions where a session
+     * might be garbage-collected while a long-running request is still in flight.
+     * It is incremented when a request begins and decremented when it finishes.
+     */
+    activeRequests: number;
+}
+/**
+ * Defines the abstract interface for a transport manager.
+ * This contract ensures that any transport manager, regardless of its statefulness,
+ * provides a consistent way to handle requests and manage its lifecycle.
+ */
+export interface TransportManager {
+    /**
+     * Handles an incoming request.
+     * @param request The standardized transport request object.
+     * @returns A promise that resolves to a TransportResponse object.
+     */
+    handleRequest(request: McpTransportRequest): Promise<TransportResponse>;
+    /**
+     * Gracefully shuts down the transport manager, cleaning up any resources.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Handles a request to explicitly delete a session.
+     * This is optional as it only applies to stateful managers.
+     * @param sessionId The ID of the session to delete.
+     * @param context The request context.
+     * @returns A promise resolving to a TransportResponse confirming closure.
+     */
+    handleDeleteRequest?(sessionId: string, context: RequestContext): Promise<TransportResponse>;
+}
+/**
+ * Extends the base TransportManager with operations specific to stateful sessions.
+ */
+export interface StatefulTransportManager extends TransportManager {
+    /**
+     * Handles a request to explicitly delete a session.
+     * This is a required implementation for stateful managers.
+     * @param sessionId The ID of the session to delete.
+     * @param context The request context.
+     * @returns A promise resolving to a TransportResponse confirming closure.
+     */
+    handleDeleteRequest(sessionId: string, context: RequestContext): Promise<TransportResponse>;
+    /**
+     * Retrieves information about a specific session.
+     * @param sessionId The ID of the session to retrieve.
+     * @returns A TransportSession object if the session exists, otherwise undefined.
+     */
+    getSession(sessionId: string): TransportSession | undefined;
+}
+export {};
+//# sourceMappingURL=transportTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transportTypes.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/transports/core/transportTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,CAAC;AAER;;GAEG;AACH,UAAU,qBAAqB;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,yBAA0B,SAAQ,qBAAqB;IACtE,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB,yBAAyB,GACzB,0BAA0B,CAAC;AAE/B;;GAEG;AACH,oBAAY,YAAY;IACtB,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,IAAI,CAAC;IAChB,cAAc,EAAE,IAAI,CAAC;IACrB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAExE;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;;;OAMG;IACH,mBAAmB,CAAC,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,gBAAgB;IAChE;;;;;;OAMG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE9B;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;CAC7D"}

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

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Defines the core types and interfaces for the transport layer abstraction.
+ * This module establishes the data contracts and abstract interfaces that decouple
+ * the MCP server's core logic from specific transport implementations like HTTP or stdio.
+ * @module src/mcp-server/transports/core/transportTypes
+ */
+/**
+ * Defines the lifecycle states of a transport session.
+ */
+export var SessionState;
+(function (SessionState) {
+    SessionState["ACTIVE"] = "ACTIVE";
+    SessionState["CLOSING"] = "CLOSING";
+})(SessionState || (SessionState = {}));
+//# sourceMappingURL=transportTypes.js.map

package/dist/mcp-server/transports/core/transportTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transportTypes.js","sourceRoot":"","sources":["../../../../src/mcp-server/transports/core/transportTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0DH;;GAEG;AACH,MAAM,CAAN,IAAY,YAGX;AAHD,WAAY,YAAY;IACtB,iCAAiB,CAAA;IACjB,mCAAmB,CAAA;AACrB,CAAC,EAHW,YAAY,KAAZ,YAAY,QAGvB"}

package/dist/mcp-server/transports/http/httpErrorHandler.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Centralized error handler for the Hono HTTP transport.
+ * This middleware intercepts errors that occur during request processing,
+ * standardizes them using the application's ErrorHandler utility, and
+ * formats them into a consistent JSON-RPC error response.
+ * @module src/mcp-server/transports/httpErrorHandler
+ */
+import { Context } from "hono";
+import { HonoNodeBindings } from "./httpTypes.js";
+/**
+ * A centralized error handling middleware for Hono.
+ * This function is registered with `app.onError()` and will catch any errors
+ * thrown from preceding middleware or route handlers.
+ *
+ * @param err - The error that was thrown.
+ * @param c - The Hono context object for the request.
+ * @returns A Response object containing the formatted JSON-RPC error.
+ */
+export declare const httpErrorHandler: (err: Error, c: Context<{
+    Bindings: HonoNodeBindings;
+    Variables: {
+        requestId?: string | number | null;
+    };
+}>) => Promise<Response>;
+//# sourceMappingURL=httpErrorHandler.d.ts.map

package/dist/mcp-server/transports/http/httpErrorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpErrorHandler.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/transports/http/httpErrorHandler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAK/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AA6BlD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,KAAK,EACV,GAAG,OAAO,CAAC;IACT,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACnD,CAAC,KACD,OAAO,CAAC,QAAQ,CA+ClB,CAAC"}

package/dist/mcp-server/transports/http/httpErrorHandler.js

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Centralized error handler for the Hono HTTP transport.
+ * This middleware intercepts errors that occur during request processing,
+ * standardizes them using the application's ErrorHandler utility, and
+ * formats them into a consistent JSON-RPC error response.
+ * @module src/mcp-server/transports/httpErrorHandler
+ */
+import { JsonRpcErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, requestContextService } from "../../../utils/index.js";
+import { logOperationStart } from "../../../utils/internal/logging-helpers.js";
+function toHttpCode(errorCode) {
+    switch (errorCode) {
+        case JsonRpcErrorCode.ParseError:
+        case JsonRpcErrorCode.InvalidRequest:
+        case JsonRpcErrorCode.InvalidParams:
+        case JsonRpcErrorCode.ValidationError:
+            return 400;
+        case JsonRpcErrorCode.MethodNotFound:
+        case JsonRpcErrorCode.NotFound:
+            return 404;
+        case JsonRpcErrorCode.Unauthorized:
+            return 401;
+        case JsonRpcErrorCode.Forbidden:
+            return 403;
+        case JsonRpcErrorCode.Conflict:
+            return 409;
+        case JsonRpcErrorCode.RateLimited:
+            return 429;
+        case JsonRpcErrorCode.Timeout:
+            return 504;
+        case JsonRpcErrorCode.ServiceUnavailable:
+            return 503;
+        default:
+            return 500;
+    }
+}
+/**
+ * A centralized error handling middleware for Hono.
+ * This function is registered with `app.onError()` and will catch any errors
+ * thrown from preceding middleware or route handlers.
+ *
+ * @param err - The error that was thrown.
+ * @param c - The Hono context object for the request.
+ * @returns A Response object containing the formatted JSON-RPC error.
+ */
+export const httpErrorHandler = async (err, c) => {
+    const context = requestContextService.createRequestContext({
+        operation: "httpErrorHandler",
+        path: c.req.path,
+        method: c.req.method,
+    });
+    logOperationStart(context, "HTTP error handler invoked.");
+    const handledError = ErrorHandler.handleError(err, {
+        operation: "httpTransport",
+        context,
+    });
+    const errorCode = handledError instanceof McpError
+        ? handledError.code
+        : JsonRpcErrorCode.InternalError;
+    const status = toHttpCode(errorCode);
+    logOperationStart(context, `Mapping error to HTTP status ${status}.`, {
+        status,
+        errorCode,
+    });
+    // Retrieve the request ID from the Hono context
+    let requestId = null;
+    try {
+        // Use c.get() which handles the retrieval safely
+        requestId = c.get("requestId") ?? null;
+    }
+    catch (_e) {
+        // Log if retrieval fails, though unlikely
+        logOperationStart(context, "Could not retrieve requestId from Hono context in error handler.");
+    }
+    c.status(status);
+    const errorResponse = {
+        jsonrpc: "2.0",
+        error: {
+            code: errorCode,
+            message: handledError.message,
+        },
+        id: requestId,
+    };
+    return c.json(errorResponse);
+};
+//# sourceMappingURL=httpErrorHandler.js.map

package/dist/mcp-server/transports/http/httpErrorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpErrorHandler.js","sourceRoot":"","sources":["../../../../src/mcp-server/transports/http/httpErrorHandler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AAG/E,SAAS,UAAU,CAAC,SAA2B;IAC7C,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,gBAAgB,CAAC,UAAU,CAAC;QACjC,KAAK,gBAAgB,CAAC,cAAc,CAAC;QACrC,KAAK,gBAAgB,CAAC,aAAa,CAAC;QACpC,KAAK,gBAAgB,CAAC,eAAe;YACnC,OAAO,GAAG,CAAC;QACb,KAAK,gBAAgB,CAAC,cAAc,CAAC;QACrC,KAAK,gBAAgB,CAAC,QAAQ;YAC5B,OAAO,GAAG,CAAC;QACb,KAAK,gBAAgB,CAAC,YAAY;YAChC,OAAO,GAAG,CAAC;QACb,KAAK,gBAAgB,CAAC,SAAS;YAC7B,OAAO,GAAG,CAAC;QACb,KAAK,gBAAgB,CAAC,QAAQ;YAC5B,OAAO,GAAG,CAAC;QACb,KAAK,gBAAgB,CAAC,WAAW;YAC/B,OAAO,GAAG,CAAC;QACb,KAAK,gBAAgB,CAAC,OAAO;YAC3B,OAAO,GAAG,CAAC;QACb,KAAK,gBAAgB,CAAC,kBAAkB;YACtC,OAAO,GAAG,CAAC;QACb;YACE,OAAO,GAAG,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EACnC,GAAU,EACV,CAGE,EACiB,EAAE;IACrB,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;QACzD,SAAS,EAAE,kBAAkB;QAC7B,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI;QAChB,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM;KACrB,CAAC,CAAC;IACH,iBAAiB,CAAC,OAAO,EAAE,6BAA6B,CAAC,CAAC;IAE1D,MAAM,YAAY,GAAG,YAAY,CAAC,WAAW,CAAC,GAAG,EAAE;QACjD,SAAS,EAAE,eAAe;QAC1B,OAAO;KACR,CAAC,CAAC;IAEH,MAAM,SAAS,GACb,YAAY,YAAY,QAAQ;QAC9B,CAAC,CAAC,YAAY,CAAC,IAAI;QACnB,CAAC,CAAC,gBAAgB,CAAC,aAAa,CAAC;IACrC,MAAM,MAAM,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IAErC,iBAAiB,CAAC,OAAO,EAAE,gCAAgC,MAAM,GAAG,EAAE;QACpE,MAAM;QACN,SAAS;KACV,CAAC,CAAC;IAEH,gDAAgD;IAChD,IAAI,SAAS,GAA2B,IAAI,CAAC;IAC7C,IAAI,CAAC;QACH,iDAAiD;QACjD,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;IACzC,CAAC;IAAC,OAAO,EAAE,EAAE,CAAC;QACZ,0CAA0C;QAC1C,iBAAiB,CACf,OAAO,EACP,kEAAkE,CACnE,CAAC;IACJ,CAAC;IAED,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACjB,MAAM,aAAa,GAAG;QACpB,OAAO,EAAE,KAAK;QACd,KAAK,EAAE;YACL,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,YAAY,CAAC,OAAO;SAC9B;QACD,EAAE,EAAE,SAAS;KACd,CAAC;IACF,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAC/B,CAAC,CAAC"}

package/dist/mcp-server/transports/http/httpTransport.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Configures and starts the HTTP MCP transport using Hono.
+ * This file has been refactored to correctly integrate Hono's streaming
+ * capabilities with the Model Context Protocol SDK's transport layer.
+ * @module src/mcp-server/transports/http/httpTransport
+ */
+import { ServerType } from "@hono/node-server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Hono } from "hono";
+import { RequestContext } from "../../../utils/index.js";
+import { TransportManager, TransportResponse } from "../core/transportTypes.js";
+import { HonoNodeBindings } from "./httpTypes.js";
+type HonoAppEnv = {
+    Bindings: HonoNodeBindings;
+    Variables: {
+        mcpResponse?: TransportResponse;
+        requestId?: string | number | null;
+    };
+};
+export declare function createHttpApp(transportManager: TransportManager, createServerInstanceFn: () => Promise<McpServer>, parentContext: RequestContext): Hono<HonoAppEnv>;
+export declare function startHttpTransport(createServerInstanceFn: () => Promise<McpServer>, parentContext: RequestContext): Promise<{
+    app: Hono<HonoAppEnv>;
+    server: ServerType;
+    transportManager: TransportManager;
+}>;
+export {};
+//# sourceMappingURL=httpTransport.d.ts.map

package/dist/mcp-server/transports/http/httpTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpTransport.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/transports/http/httpTransport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAS,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAW,IAAI,EAAQ,MAAM,MAAM,CAAC;AAU3C,OAAO,EAGL,cAAc,EAEf,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAIhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AA0NlD,KAAK,UAAU,GAAG;IAChB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE;QACT,WAAW,CAAC,EAAE,iBAAiB,CAAC;QAChC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;KACpC,CAAC;CACH,CAAC;AAEF,wBAAgB,aAAa,CAC3B,gBAAgB,EAAE,gBAAgB,EAClC,sBAAsB,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EAChD,aAAa,EAAE,cAAc,GAC5B,IAAI,CAAC,UAAU,CAAC,CAgPlB;AAED,wBAAsB,kBAAkB,CACtC,sBAAsB,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EAChD,aAAa,EAAE,cAAc,GAC5B,OAAO,CAAC;IACT,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,gBAAgB,EAAE,gBAAgB,CAAC;CACpC,CAAC,CAoHD"}