@makaio/framework 1.0.0-dev-1781117225170 → 1.0.0-dev-1781354548379

package/dist/mcp-http-server/index.d.mts

@@ -201,6 +201,17 @@ interface McpServerOptions {
   agentContext?: McpAgentContext$1;
   /** Optional MCP tool discovery customization. */
   toolDiscovery?: McpToolDiscoveryOptions;
+  /**
+   * Optional callback invoked exactly once when the stdio transport closes.
+   *
+   * Fired on whichever of these happens first: the client detaches (stdin EOF),
+   * the SDK transport fires its own `onclose` hook, or an explicit
+   * {@link StdioMcpServerHandle.close} call completes. Subsequent triggers are
+   * suppressed so the callback is guaranteed to fire at most once.
+   *
+   * Only consulted for `transport: 'stdio'`; ignored for HTTP.
+   */
+  onclose?: () => void;
 }
 /**
  * Result returned by {@link startMcpServer} for the stdio transport.
@@ -245,24 +256,68 @@ interface CreateMcpServerOptions {
   resolveContextOverrides?: ResolveContextOverrides;
 }
 /**
- * Options accepted by {@link startHttpMcpServer}.
- *
- * Extends the transport-agnostic {@link McpServerOptions} fields (minus
- * `transport`, which is always `'http'` for this function) with an optional
- * callback for resolving session-stable context overrides at tool-call time.
+ * Transport-agnostic options shared by {@link createHttpMcpHandler} and
+ * {@link startHttpMcpServer}.  These fields configure the MCP server and its
+ * attached transport without prescribing how the resulting handler is mounted
+ * onto an HTTP stack.
  */
-interface HttpMcpServerOptions extends Omit<McpServerOptions, 'transport'> {
-  /** Optional callback for session-stable context override resolution. */
-  resolveContextOverrides?: ResolveContextOverrides;
+interface HttpMcpHandlerOptions {
+  /** Agent context for HTTP transport routing. */
+  agentContext?: McpAgentContext$1;
+  /** Optional MCP tool discovery customization. */
+  toolDiscovery?: McpToolDiscoveryOptions;
   /**
-   * Optional callback invoked when the HTTP transport closes.
+   * Optional callback invoked when the underlying MCP transport closes.
    *
    * Called synchronously by the MCP SDK's transport `onclose` hook — that is,
-   * when {@link HttpMcpServerHandle.close} has been called and the transport
-   * has finished closing. Intended for best-effort resource cleanup (e.g.
-   * flushing session registries) without blocking the close path.
+   * after {@link HttpMcpHandlerHandle.close} (or {@link HttpMcpServerHandle.close})
+   * has been called and the transport has finished tearing down.  Intended for
+   * best-effort resource cleanup (e.g. flushing session registries) without
+   * blocking the close path.
+   *
+   * When used via {@link startHttpMcpServer}, the callback fires after the MCP
+   * transport closes, which occurs during the combined server-and-transport
+   * teardown initiated by {@link HttpMcpServerHandle.close}.
    */
   onclose?: () => void;
+  /** Optional callback for session-stable context override resolution. */
+  resolveContextOverrides?: ResolveContextOverrides;
+}
+/**
+ * Options accepted by {@link startHttpMcpServer}.
+ *
+ * Extends {@link HttpMcpHandlerOptions} with `port`, which controls which
+ * TCP port the internally-created `http.Server` listens on.
+ */
+interface HttpMcpServerOptions extends HttpMcpHandlerOptions {
+  /** Port for HTTP transport. When omitted or 0, OS assigns an available port. */
+  port?: number;
+}
+/**
+ * Result returned by {@link createHttpMcpHandler}.
+ *
+ * Provides a Node.js-compatible request handler that can be mounted on any
+ * HTTP stack that exposes the raw `IncomingMessage` / `ServerResponse` pair,
+ * plus lifecycle handles for the underlying MCP server. See
+ * {@link createHttpMcpHandler} for usage and mounting examples.
+ */
+interface HttpMcpHandlerHandle {
+  /**
+   * Mount this on any Node-compatible HTTP stack.
+   *
+   * The handler parses the raw request body internally; do not pre-read or
+   * pre-parse the body before passing the request to this function.
+   */
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => void;
+  /** Context registry for registering and unregistering agent sessions. */
+  readonly contextRegistry: IMcpContextRegistry;
+  /**
+   * Gracefully close the MCP server and its transport.
+   *
+   * Idempotent: repeated calls await the same underlying close operation and
+   * do not trigger a second teardown.
+   */
+  close(): Promise<void>;
 }
 /**
  * Create and configure MCP server.
@@ -317,16 +372,72 @@ declare function createMcpServer(bus: IMakaioBus, sessionId: string, options?: C
  * Create a framework-agnostic HTTP request handler that delegates to
  * {@link StreamableHTTPServerTransport.handleRequest}.
  *
- * This is the seam for attaching MCP to a shared HTTP server in the future.
- * The transport handles body parsing internally and we do not pre-parse the body,
- * otherwise the request stream would be consumed before MCP can read it.
+ * **External consumers should prefer {@link createHttpMcpHandler}**, which
+ * constructs the transport internally so no MCP SDK type needs to appear in
+ * caller code.  This lower-level function is exposed for internal composition
+ * and testing.
+ *
+ * The transport handles body parsing internally; do not pre-parse the body
+ * before calling this handler, as that would consume the request stream before
+ * MCP can read it.
  * @param transport - Streamable HTTP transport instance connected to the server.
  * @param onBeforeDispatch - Optional hook called synchronously before request dispatch.
  * @returns Node.js-compatible request handler.
  */
 declare function createMcpRequestHandler(transport: StreamableHTTPServerTransport, onBeforeDispatch?: (req: IncomingMessage, res: ServerResponse) => void): (req: IncomingMessage, res: ServerResponse) => void;
+/**
+ * Create a mountable MCP handler without starting a dedicated HTTP server.
+ *
+ * Use this when you want to embed MCP into an existing HTTP application rather
+ * than running MCP on its own port.  The returned {@link HttpMcpHandlerHandle.handler}
+ * is a plain Node.js `(req, res) => void` function that you can wire into any
+ * framework exposing the raw `IncomingMessage` / `ServerResponse` pair (e.g.
+ * Hono's Node adapter via `(c) => { handler(c.env.incoming, c.env.outgoing); }`).
+ *
+ * The MCP SDK transport is constructed and managed internally — no MCP SDK
+ * types appear in the public API.
+ *
+ * **Auth / middleware is the consumer's responsibility.** Run authentication,
+ * rate limiting, or logging in the surrounding HTTP stack *before* delegating
+ * to the returned handler.
+ *
+ * Closing the handle shuts down the MCP server and its transport; active
+ * HTTP connections are left to the caller's HTTP stack.
+ * @param bus - Bus instance for tool execution and approval RPC.
+ * @param options - Handler options; all fields are optional.
+ * @returns Handle with the request handler function, context registry, and
+ *   an idempotent `close()` method.
+ * @example
+ * ```ts
+ * import * as http from 'node:http';
+ * import { createHttpMcpHandler } from '@makaio/framework/mcp-http-server';
+ *
+ * const { handler, close } = await createHttpMcpHandler(bus);
+ *
+ * const httpServer = http.createServer((req, res) => {
+ *   if (req.url?.startsWith('/mcp')) {
+ *     handler(req, res);
+ *   } else {
+ *     res.writeHead(404).end();
+ *   }
+ * });
+ *
+ * httpServer.listen(3000);
+ *
+ * process.once('SIGTERM', async () => {
+ *   httpServer.close();
+ *   await close();
+ * });
+ * ```
+ */
+declare function createHttpMcpHandler(bus: IMakaioBus, options?: HttpMcpHandlerOptions): Promise<HttpMcpHandlerHandle>;
 /**
  * Start a standalone HTTP MCP server on a new `http.Server`.
+ *
+ * This is a convenience wrapper around {@link createHttpMcpHandler} that also
+ * creates an `http.Server`, binds it to a TCP port, and manages connection
+ * draining on close.  Use {@link createHttpMcpHandler} directly when you need
+ * to embed MCP into an existing HTTP application.
  * @param bus - Bus instance.
  * @param options - Server options; `port` defaults to 0 (OS-assigned).
  *   Pass `resolveContextOverrides` to supply session-stable context overrides
@@ -338,9 +449,11 @@ declare function startHttpMcpServer(bus: IMakaioBus, options?: HttpMcpServerOpti
  * Start MCP server with the configured transport.
  *
  * For the stdio transport, returns a {@link StdioMcpServerHandle} whose
- * `close()` method gracefully tears down the MCP server. Signal handling
- * is intentionally left to the composition root — library code must not
- * own process-global resources such as `process.on('SIGINT')`.
+ * `close()` method gracefully tears down the MCP server. Pass
+ * `options.onclose` to receive a single callback when the transport closes for
+ * any reason (client detach via stdin EOF, or explicit `handle.close()`).
+ * Signal handling is intentionally left to the composition root — library code
+ * must not own process-global resources such as `process.on('SIGINT')`.
  * @param bus - Bus instance.
  * @param sessionId - Session identifier (used for stdio transport).
  * @param options - Server options; defaults to stdio transport.
@@ -558,4 +671,4 @@ interface McpClientBridgeOptions {
  */
 declare function startMcpClientBridge(options: McpClientBridgeOptions): Promise<McpClientBridgeHandle>;
 //#endregion
-export { APPROVE_TOOL_NAME, type CreateMcpServerOptions, type HttpMcpServerHandle, type HttpMcpServerOptions, type IMcpContextRegistry, type McpAgentContext, type McpBridgedTool, type McpCallToolResult, type McpClientBridgeHandle, type McpClientBridgeOptions, McpContextRegistry, type McpResolvedTools, McpServerBridgeService, type McpServerOptions, type McpToolDiscoveryIdentity, type McpToolDiscoveryOptions, type McpToolEntry, type PluginToolsetMap, type RequestToolApproval, type ResolveContextOverrides, type StdioMcpServerHandle, type ToolApproveRequestPayload, type ToolApproveResponse, createMcpRequestHandler, createMcpServer, resolveMcpTools, startHttpMcpServer, startMcpClientBridge, startMcpServer, toolInfoToMcpTool };
+export { APPROVE_TOOL_NAME, type CreateMcpServerOptions, type HttpMcpHandlerHandle, type HttpMcpHandlerOptions, type HttpMcpServerHandle, type HttpMcpServerOptions, type IMcpContextRegistry, type McpAgentContext, type McpBridgedTool, type McpCallToolResult, type McpClientBridgeHandle, type McpClientBridgeOptions, McpContextRegistry, type McpResolvedTools, McpServerBridgeService, type McpServerOptions, type McpToolDiscoveryIdentity, type McpToolDiscoveryOptions, type McpToolEntry, type PluginToolsetMap, type RequestToolApproval, type ResolveContextOverrides, type StdioMcpServerHandle, type ToolApproveRequestPayload, type ToolApproveResponse, createHttpMcpHandler, createMcpRequestHandler, createMcpServer, resolveMcpTools, startHttpMcpServer, startMcpClientBridge, startMcpServer, toolInfoToMcpTool };