@makaio/framework 1.0.0-dev-1781023871421 → 1.0.0-dev-1781081952714

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

@@ -0,0 +1,561 @@
+import { IMakaioBus } from "@makaio/framework/bus";
+import { McpAgentContext, McpAgentContext as McpAgentContext$1, ToolExecutionContextOverrides } from "@makaio/framework/contracts";
+import { BaseService } from "@makaio/framework/service-base";
+import { McpToolDefinition, ToolInfo } from "@makaio/framework/tools";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Server as Server$1 } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+
+//#region subsystems/mcp-http-server/src/context-registry.d.ts
+/**
+ * Registry mapping adapterSessionId to agent context.
+ *
+ * The adapter registers context before spawning Claude CLI; the MCP server
+ * reads it when handling approval requests (via adapterSessionId from URL query).
+ */
+interface IMcpContextRegistry {
+  /**
+   * Register agent context for an adapter session.
+   * @param adapterSessionId - Adapter session identifier
+   * @param context - Agent context to store
+   */
+  register(adapterSessionId: string, context: McpAgentContext$1): void;
+  /**
+   * Retrieve agent context for an adapter session.
+   * @param adapterSessionId - Adapter session identifier
+   * @returns Stored agent context, or undefined if not registered
+   */
+  get(adapterSessionId: string): McpAgentContext$1 | undefined;
+  /**
+   * Remove agent context for an adapter session.
+   * @param adapterSessionId - Adapter session identifier
+   */
+  unregister(adapterSessionId: string): void;
+}
+/**
+ * Simple Map-backed implementation of {@link IMcpContextRegistry}.
+ *
+ * Created once per adapter instance, shared with the HTTP MCP server so
+ * approval requests can resolve agent context from the URL query param.
+ */
+declare class McpContextRegistry implements IMcpContextRegistry {
+  private readonly registry;
+  /**
+   * Register agent context for an adapter session.
+   * @param adapterSessionId - Adapter session identifier
+   * @param context - Agent context to store
+   */
+  register(adapterSessionId: string, context: McpAgentContext$1): void;
+  /**
+   * Retrieve agent context for an adapter session.
+   * @param adapterSessionId - Adapter session identifier
+   * @returns Stored agent context, or undefined if not registered
+   */
+  get(adapterSessionId: string): McpAgentContext$1 | undefined;
+  /**
+   * Remove agent context for an adapter session.
+   * @param adapterSessionId - Adapter session identifier
+   */
+  unregister(adapterSessionId: string): void;
+}
+//#endregion
+//#region subsystems/mcp-http-server/src/approve-tool.d.ts
+/** MCP tool name for the permission prompt handler. */
+declare const APPROVE_TOOL_NAME = "approve";
+/** Payload forwarded to `agent.toolApprove`. */
+interface ToolApproveRequestPayload {
+  toolName: string;
+  args: Record<string, unknown>;
+  toolCallId: string;
+  agentId: string;
+  adapterId: string;
+  adapterName: string;
+  adapterSessionId: string;
+  /** Makaio session ID — required for approval routing to the owning tab. */
+  sessionId: string;
+}
+/** Minimal response shape consumed from `agent.toolApprove`. */
+type ToolApproveResponse = {
+  action: 'allow';
+  updatedInput?: Record<string, unknown>;
+} | {
+  action: 'deny';
+  message?: string;
+};
+/** Function seam for approval RPC. */
+type RequestToolApproval = (payload: ToolApproveRequestPayload) => Promise<ToolApproveResponse>;
+//#endregion
+//#region subsystems/mcp-http-server/src/tool-discovery.d.ts
+/**
+ * Maps a runtime toolset name to the plugin that owns it.
+ * When present, tools in the toolset receive an MCP name of `{pluginName}.{toolName}`.
+ */
+type PluginToolsetMap = Record<string, string>;
+/**
+ * Describes a single resolved MCP tool entry, capturing the relationship between
+ * the MCP-visible name and the original runtime tool name.
+ */
+interface McpToolEntry {
+  /** The MCP-visible name used in `tools/list` and `tools/call`. */
+  mcpName: string;
+  /** The original tool name as registered in the ToolRegistry. */
+  sourceToolName: string;
+  /** The toolset this tool belongs to. */
+  toolsetName: string;
+}
+/**
+ * Result of resolving MCP tools from the registry.
+ */
+interface McpResolvedTools {
+  /** MCP-compatible tool definitions ready to send in `tools/list` responses. */
+  tools: McpToolDefinition[];
+  /**
+   * Bidirectional lookup map from MCP name to tool entry.
+   * Use `byMcpName.get(mcpName)?.sourceToolName` to map a `tools/call` name back
+   * to the runtime tool name for execution.
+   */
+  byMcpName: Map<string, McpToolEntry>;
+}
+/**
+ * Adapter identity fields for tool discovery policy filtering.
+ *
+ * When present, these fields are forwarded to `ToolSubjects.list` so the
+ * tool registry can apply per-adapter policy (e.g., allowedAdapters checks).
+ */
+interface McpToolDiscoveryIdentity {
+  /** Adapter identifier for policy filtering. */
+  readonly adapterId?: string;
+  /** Human-readable adapter name for policy filtering. */
+  readonly adapterName?: string;
+}
+/**
+ * Options for MCP tool discovery.
+ */
+interface McpToolDiscoveryOptions {
+  /**
+   * Maps toolset names to the plugin that owns them.
+   * Tools in a plugin-owned toolset receive an MCP name of `{pluginName}.{toolName}`.
+   * Tools in non-plugin toolsets receive bare `{toolName}` unless a collision occurs.
+   */
+  pluginToolsets?: PluginToolsetMap;
+  /**
+   * Official filtering seam for controlling which tools are exposed via MCP.
+   *
+   * Receives the full list of candidate tools (after bus query or static fallback) and
+   * returns the subset to expose. Return an empty array to suppress all tools.
+   * Return the input unchanged (default) to expose all tools.
+   *
+   * Use this hook to implement allow-lists, capability checks, or runtime feature flags
+   * without modifying the registry or toolsets themselves.
+   * @param tools - All candidate tools available in the registry
+   * @returns Subset of tools to expose via MCP
+   */
+  getExposedTools?: (tools: ToolInfo[]) => ToolInfo[];
+  /**
+   * Static fallback tool list used when `ToolSubjects.list` has no registered handler
+   * on the bus (e.g., no `ToolRegistry` is running in-process).
+   * If omitted and the bus has no handler, the result will be empty.
+   */
+  staticFallback?: ToolInfo[];
+}
+/**
+ * Resolves the MCP-visible tool list from the bus, with collision-safe naming.
+ *
+ * Resolution algorithm:
+ * 1. Query `ToolSubjects.list` via `bus.requestOptional`. If no handler is registered,
+ *    fall back to `options.staticFallback` (empty by default).
+ * 2. Apply `options.getExposedTools` filter (identity by default).
+ * 3. Assign tentative MCP names: plugin-owned toolsets get `{pluginName}.{toolName}`,
+ *    all others get bare `{toolName}`.
+ * 4. Detect collisions: any tentative name claimed by two or more tools is resolved to
+ *    `{toolsetName}.{toolName}` for every tool sharing that name.
+ * 5. Return `McpResolvedTools` with the final tool list and a `byMcpName` lookup map.
+ * @param bus - Bus instance used to query the live tool registry
+ * @param options - Discovery options (plugin map, filter hook, static fallback)
+ * @param identity - Optional adapter identity for per-adapter policy filtering
+ * @returns Resolved MCP tools with bidirectional name mapping
+ */
+declare function resolveMcpTools(bus: IMakaioBus, options?: McpToolDiscoveryOptions, identity?: McpToolDiscoveryIdentity): Promise<McpResolvedTools>;
+/**
+ * Convert a `ToolInfo` from the registry to an `McpToolDefinition`.
+ *
+ * Used internally by `resolveMcpTools` and exposed for consumers that build the tool list outside
+ * of `resolveMcpTools` (e.g., static registration paths).
+ * @param tool - Tool info entry with optional inputSchema
+ * @param mcpName - MCP-visible name to assign (may differ from `tool.name`)
+ * @returns MCP-compatible tool definition
+ */
+declare function toolInfoToMcpTool(tool: ToolInfo, mcpName: string): McpToolDefinition;
+//#endregion
+//#region subsystems/mcp-http-server/src/server.d.ts
+/**
+ * Options for configuring MCP server startup.
+ */
+interface McpServerOptions {
+  /** Required. Defaults to `'stdio'` when using {@link startMcpServer}. */
+  transport: 'stdio' | 'http';
+  /** Port for HTTP transport. When omitted or 0, OS assigns an available port. */
+  port?: number;
+  /** Agent context for HTTP transport routing. */
+  agentContext?: McpAgentContext$1;
+  /** Optional MCP tool discovery customization. */
+  toolDiscovery?: McpToolDiscoveryOptions;
+}
+/**
+ * Result returned by {@link startMcpServer} for the stdio transport.
+ */
+interface StdioMcpServerHandle {
+  /** Gracefully close the MCP server and stdio transport. */
+  close: () => Promise<void>;
+}
+/**
+ * Result returned by {@link startHttpMcpServer}.
+ */
+interface HttpMcpServerHandle {
+  /** OS-assigned port the HTTP server is listening on. */
+  port: number;
+  /** Context registry for registering/unregistering agent sessions. */
+  contextRegistry: IMcpContextRegistry;
+  /** Gracefully close the HTTP server and MCP transport. */
+  close: () => Promise<void>;
+}
+/**
+ * Callback that resolves session-stable context overrides for a given
+ * adapter session ID.
+ *
+ * Invoked on every tool-call request. When the session is found, its
+ * return value overrides the default fallback context
+ * `{ cwd: process.cwd(), sessionId }`. When the session is unknown or
+ * the header is absent, returning `undefined` keeps the fallback.
+ * @param adapterSessionId - The adapter session ID extracted from request
+ *   headers, or `undefined` when the header is absent.
+ * @returns Resolved context overrides, or `undefined` to use the fallback.
+ */
+type ResolveContextOverrides = (adapterSessionId: string | undefined) => ToolExecutionContextOverrides | undefined;
+/**
+ * Options for {@link createMcpServer}.
+ */
+interface CreateMcpServerOptions {
+  /** Registry for resolving agent context by adapterSessionId. When present, the `approve` tool is exposed. */
+  contextRegistry?: IMcpContextRegistry;
+  /** Optional tool discovery customization. */
+  toolDiscovery?: McpToolDiscoveryOptions;
+  /** Optional callback to resolve session-stable context overrides from an adapter session ID at tool-call time. */
+  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.
+ */
+interface HttpMcpServerOptions extends Omit<McpServerOptions, 'transport'> {
+  /** Optional callback for session-stable context override resolution. */
+  resolveContextOverrides?: ResolveContextOverrides;
+  /**
+   * Optional callback invoked when the HTTP 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.
+   */
+  onclose?: () => void;
+}
+/**
+ * Create and configure MCP server.
+ *
+ * **Freshness contract:** Tool lists are resolved fresh on every MCP `tools/list` and
+ * `tools/call` request. There is no caching between calls.
+ *
+ * **Side-effect:** Subscribes to {@link ToolSubjects.registryChanged} on `bus` and
+ * sends `notifications/tools/list_changed` to connected MCP clients on each emission.
+ * Calling `server.close()` unsubscribes this listener; connected transport closure
+ * also reaches the same idempotent cleanup through the SDK's `onclose` hook.
+ * @param bus - Bus instance for tool execution and approval RPC.
+ * @param sessionId - Session identifier for tool execution context.
+ * @param options - Optional server configuration.
+ * @returns Configured MCP {@link Server} instance.
+ */
+declare function createMcpServer(bus: IMakaioBus, sessionId: string, options?: CreateMcpServerOptions): Promise<Server$1<{
+  method: string;
+  params?: {
+    [x: string]: unknown;
+    _meta?: {
+      [x: string]: unknown;
+      progressToken?: string | number | undefined;
+      "io.modelcontextprotocol/related-task"?: {
+        taskId: string;
+      } | undefined;
+    } | undefined;
+  } | undefined;
+}, {
+  method: string;
+  params?: {
+    [x: string]: unknown;
+    _meta?: {
+      [x: string]: unknown;
+      progressToken?: string | number | undefined;
+      "io.modelcontextprotocol/related-task"?: {
+        taskId: string;
+      } | undefined;
+    } | undefined;
+  } | undefined;
+}, {
+  [x: string]: unknown;
+  _meta?: {
+    [x: string]: unknown;
+    progressToken?: string | number | undefined;
+    "io.modelcontextprotocol/related-task"?: {
+      taskId: string;
+    } | undefined;
+  } | undefined;
+}>>;
+/**
+ * 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.
+ * @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;
+/**
+ * Start a standalone HTTP MCP server on a new `http.Server`.
+ * @param bus - Bus instance.
+ * @param options - Server options; `port` defaults to 0 (OS-assigned).
+ *   Pass `resolveContextOverrides` to supply session-stable context overrides
+ *   at tool-call time (used by {@link McpServerBridgeService}).
+ * @returns Handle exposing the OS-assigned port, context registry, and a close function.
+ */
+declare function startHttpMcpServer(bus: IMakaioBus, options?: HttpMcpServerOptions): Promise<HttpMcpServerHandle>;
+/**
+ * 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')`.
+ * @param bus - Bus instance.
+ * @param sessionId - Session identifier (used for stdio transport).
+ * @param options - Server options; defaults to stdio transport.
+ * @returns A handle exposing a `close()` function for both transports.
+ *   For HTTP transport the handle additionally exposes the OS-assigned
+ *   port and the context registry.
+ */
+declare function startMcpServer(bus: IMakaioBus, sessionId: string, options?: McpServerOptions): Promise<HttpMcpServerHandle | StdioMcpServerHandle>;
+//#endregion
+//#region subsystems/mcp-http-server/src/mcp-server-bridge-service.d.ts
+/**
+ * Singleton bus service that manages the HTTP MCP server lifecycle.
+ *
+ * Handles `mcp.session.register` and `mcp.session.unregister` bus subjects.
+ * The HTTP MCP server is started lazily on the first `session.register` call
+ * using a coalescing promise so concurrent registrations never start two
+ * server instances.
+ *
+ * The service maintains three parallel session stores:
+ * - `pinnedSessions` (plain Map) — sessions exempt from both TTL sweep and
+ *   LRU count-eviction; only removed by explicit `mcp.session.unregister` or
+ *   on server close
+ * - `sessions` (QuickLRU) — non-pinned sessions subject to TTL/LRU eviction
+ * - `contextRegistry` (Map-backed, inside the HTTP server handle) — source of
+ *   truth for the MCP server's per-request routing
+ *
+ * The `resolveContextOverrides` callback threaded into `startHttpMcpServer`
+ * bridges these stores so tool execution always uses session-stable
+ * context overrides rather than per-process fallbacks.
+ */
+declare class McpServerBridgeService extends BaseService {
+  private mcpHandle;
+  private startPromise;
+  private readonly sessions;
+  /**
+   * Sessions that are exempt from LRU count-eviction and TTL sweep.
+   * Pinned sessions have fundamentally different lifecycle semantics — no
+   * expiry — so they are kept in a plain Map separate from the QuickLRU.
+   * Only an explicit `mcp.session.unregister` or a server close removes them.
+   * A soft cap of {@link MAX_PINNED_SESSION_COUNT} is enforced via a warning
+   * to detect unregister-path bugs early without disrupting functionality.
+   */
+  private readonly pinnedSessions;
+  /**
+   * @param bus - Bus instance used for handler registration.
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Register bus handlers and start the TTL sweep interval.
+   * @returns Promise that resolves when all handlers are registered.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Resolve context overrides for an adapter session.
+   *
+   * Updates `lastActivity` on access so recently-used sessions are not
+   * swept by the TTL interval.
+   * @param adapterSessionId - Adapter session identifier to look up.
+   * @returns The stored context overrides, or `undefined` if not found.
+   */
+  private resolveOverrides;
+  /**
+   * Ensure the HTTP MCP server is running, starting it if necessary.
+   *
+   * Uses a coalescing promise so concurrent callers never start two servers.
+   * The promise is cleared on both success and failure so a transient startup
+   * error does not permanently block retries.
+   * @returns The running HTTP MCP server handle.
+   */
+  private ensureStarted;
+}
+//#endregion
+//#region subsystems/mcp-http-server/src/mcp-client-bridge.d.ts
+/**
+ * A tool discovered from an MCP server and bridged for bus registration.
+ */
+interface McpBridgedTool {
+  /** The tool's name as returned by the MCP server. */
+  readonly name: string;
+  /** Human-readable description. */
+  readonly description: string;
+  /** JSON Schema for the tool's input parameters. */
+  readonly inputSchema: unknown;
+}
+/**
+ * Return type of {@link McpClientBridgeHandle.callTool}.
+ *
+ * Mirrors the shape returned by the MCP SDK client so callers get the raw
+ * result without re-parsing content.
+ */
+type McpCallToolResult = Awaited<ReturnType<Client['callTool']>>;
+/**
+ * Handle for an active MCP client bridge.
+ *
+ * Returned by {@link startMcpClientBridge}. Callers hold this handle for the
+ * lifetime of the spawned MCP subprocess, then call {@link close} to tear down
+ * the transport and the child process.
+ */
+interface McpClientBridgeHandle {
+  /**
+   * Currently known tools from the MCP server.
+   *
+   * Updated automatically whenever the server sends
+   * `notifications/tools/list_changed` (requires
+   * {@link McpClientBridgeOptions.onToolsChanged} to be provided so the bridge
+   * subscribes to list-change events).
+   */
+  readonly tools: readonly McpBridgedTool[];
+  /**
+   * Names of the currently known tools.
+   *
+   * Convenience accessor over {@link tools} — equivalent to
+   * `handle.tools.map(t => t.name)`.
+   */
+  readonly toolNames: readonly string[];
+  /**
+   * Proxy a tool call to the connected MCP server.
+   * @param name - Tool name as advertised by the MCP server.
+   * @param args - Tool input arguments.
+   * @returns The raw MCP call-tool result.
+   */
+  callTool(name: string, args: Record<string, unknown>): Promise<McpCallToolResult>;
+  /**
+   * Close the MCP client and terminate the subprocess.
+   * @returns Promise that resolves when the transport has been fully closed.
+   */
+  close(): Promise<void>;
+}
+/**
+ * Options for {@link startMcpClientBridge}.
+ */
+interface McpClientBridgeOptions {
+  /**
+   * The executable to spawn as an MCP server subprocess.
+   *
+   * Can be an absolute path or a name resolvable via `PATH`.
+   */
+  readonly command: string;
+  /**
+   * Command-line arguments forwarded to the subprocess.
+   * Defaults to an empty array when omitted.
+   */
+  readonly args?: readonly string[];
+  /**
+   * Environment variables for the spawned subprocess.
+   *
+   * When omitted the SDK's {@link getDefaultEnvironment} is used, which
+   * inherits a safe subset of the parent environment.
+   */
+  readonly env?: Readonly<Record<string, string>>;
+  /**
+   * Working directory for the spawned subprocess.
+   *
+   * Forwarded verbatim to the stdio transport. When omitted, the current
+   * working directory of the parent process is inherited.
+   */
+  readonly cwd?: string;
+  /**
+   * Extension name used as the MCP client identifier.
+   *
+   * Surfaced as `name: 'makaio-{extensionName}'` in the MCP handshake, making
+   * server-side logs attributable to the correct extension.
+   */
+  readonly extensionName: string;
+  /**
+   * Callback invoked when the MCP server signals that its tool list has changed.
+   *
+   * Receives the refreshed tool list after the server sends
+   * `notifications/tools/list_changed`. Callers should use this to update any
+   * cached tool registrations.
+   * @param tools - Updated list of bridged tools.
+   */
+  readonly onToolsChanged?: (tools: McpBridgedTool[]) => void;
+  /**
+   * Optional Makaio bus that receives MCP-backed `tool.list` and `tool.execute` handlers.
+   *
+   * When provided, the bridge exposes the connected MCP server's tools through
+   * the standard ToolSubjects contract while preserving the local handle API.
+   */
+  readonly bus?: IMakaioBus;
+  /**
+   * Toolset name used for bus-visible MCP tools.
+   *
+   * Defaults to {@link extensionName}, matching detached extension identity.
+   */
+  readonly toolsetName?: string;
+  /**
+   * Priority for bridge-owned bus handlers.
+   *
+   * Defaults above the regular tool registry so the bridge can merge `tool.list`
+   * results and route only the MCP tools it owns before delegating.
+   */
+  readonly busHandlerPriority?: number;
+}
+/**
+ * Spawn an MCP server subprocess via stdio, connect to it as an MCP client,
+ * and discover its tool list.
+ *
+ * The spawned subprocess communicates over its stdin/stdout using the MCP
+ * JSON-RPC protocol. The SDK's {@link StdioClientTransport} manages the child
+ * process lifecycle; callers must call {@link McpClientBridgeHandle.close} to
+ * terminate it cleanly.
+ *
+ * When {@link McpClientBridgeOptions.onToolsChanged} is provided, the bridge
+ * subscribes to `notifications/tools/list_changed` via the SDK's built-in
+ * `listChanged.tools` handler so that tool list updates are propagated
+ * automatically. The handle's {@link McpClientBridgeHandle.tools} and
+ * {@link McpClientBridgeHandle.toolNames} getters reflect the latest known
+ * list, updated each time the server signals a change.
+ *
+ * If `listTools()` fails after the transport has already connected, the bridge
+ * closes the client and re-throws so no subprocess is left orphaned.
+ * @param options - Bridge configuration.
+ * @returns Handle exposing the live tool list and proxy methods.
+ */
+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 };