kernl 0.1.1

package/src/mcp/base.ts

@@ -0,0 +1,162 @@
+import { Logger } from "@/lib/logger";
+
+import { MCPTool, MCPToolFilter, CallToolResultContent } from "./types";
+
+export const DEFAULT_STDIO_MCP_CLIENT_LOGGER_NAME = "kernl:stdio-mcp-client";
+export const DEFAULT_SSE_MCP_CLIENT_LOGGER_NAME = "kernl:sse-mcp-client";
+export const DEFAULT_STREAMABLE_HTTP_MCP_CLIENT_LOGGER_NAME =
+  "kernl:streamable-http-mcp-client";
+
+/**
+ * @example
+ *
+ *  const server = new MCPServerStdio({
+ *    id: 'Filesystem Server',
+ *    command: 'npx',
+ *    args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir']
+ *  });
+ *
+ *  await server.connect();  // Establishes connection to the MCP server process
+ */
+
+/**
+ * Cache storage for MCP tools by server id.
+ * Enables reusing tool definitions across multiple agent executions.
+ */
+const _cachedTools: Record<string, MCPTool[]> = {};
+
+/**
+ * Interface for MCP server implementations.
+ * Provides methods for connecting, listing tools, calling tools, and cleanup.
+ */
+export interface MCPServer {
+  /**
+   * The unique identifier for this MCP server.
+   */
+  readonly id: string;
+
+  /**
+   * Whether to cache the tools list after first fetch.
+   */
+  cacheToolsList: boolean;
+
+  /**
+   * Filter to control which tools are exposed to agents.
+   * Always a callable function. Defaults to allowing all tools.
+   */
+  toolFilter: MCPToolFilter;
+
+  /**
+   * Establishes connection to the MCP server.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Closes the connection and cleans up resources.
+   */
+  close(): Promise<void>;
+
+  /**
+   * Fetches the list of available tools from the server.
+   */
+  listTools(): Promise<MCPTool[]>;
+
+  /**
+   * Executes a tool on the server with the provided arguments.
+   */
+  callTool(
+    toolName: string,
+    args: Record<string, unknown> | null,
+  ): Promise<CallToolResultContent>;
+
+  /**
+   * Clears any cached tools, forcing a fresh fetch on next request.
+   */
+  invalidateCache(): Promise<void>;
+}
+
+/**
+ * Base abstract class for MCP server implementations.
+ * Provides common caching logic.
+ */
+export abstract class BaseMCPServer implements MCPServer {
+  abstract readonly id: string;
+  public cacheToolsList: boolean;
+  public toolFilter: MCPToolFilter;
+  protected logger: Logger;
+  protected _cachedTools: MCPTool[] | undefined = undefined;
+  protected _cacheDirty = true;
+
+  constructor(options: {
+    cacheToolsList?: boolean;
+    toolFilter?: MCPToolFilter;
+    logger: Logger;
+  }) {
+    this.logger = options.logger;
+    this.cacheToolsList = options.cacheToolsList ?? false;
+    this.toolFilter = options.toolFilter ?? (async () => true);
+  }
+
+  /**
+   * Establishes connection to the MCP server.
+   */
+  abstract connect(): Promise<void>;
+
+  /**
+   * Closes the connection and cleans up resources.
+   */
+  abstract close(): Promise<void>;
+
+  /**
+   * Executes a tool on the server with the provided arguments.
+   */
+  abstract callTool(
+    toolName: string,
+    args: Record<string, unknown> | null,
+  ): Promise<CallToolResultContent>;
+
+  /**
+   * Fetches the list of available tools from the server.
+   * Handles caching and static filtering automatically.
+   */
+  async listTools(): Promise<MCPTool[]> {
+    if (this.cacheToolsList && !this._cacheDirty && this._cachedTools) {
+      return this._cachedTools;
+    }
+
+    this._cacheDirty = false;
+    let tools = await this._listTools();
+
+    // Apply static server-level filter (without context)
+    // This is for static filtering like allowlist/blocklist
+    const filteredTools: MCPTool[] = [];
+    for (const tool of tools) {
+      // Pass empty context for static filtering
+      const allowed = await this.toolFilter({} as any, tool);
+      if (allowed) {
+        filteredTools.push(tool);
+      }
+    }
+    tools = filteredTools;
+
+    if (this.cacheToolsList) {
+      this._cachedTools = tools;
+    }
+
+    return tools;
+  }
+
+  /**
+   * Clears any cached tools, forcing a fresh fetch on next request.
+   */
+  async invalidateCache(): Promise<void> {
+    delete _cachedTools[this.id];
+    this._cacheDirty = true;
+  }
+
+  /**
+   * Internal implementation: Fetches tools from the server (without caching logic).
+   * Subclasses implement the transport-specific logic.
+   */
+  protected abstract _listTools(): Promise<MCPTool[]>;
+}

package/src/mcp/http.ts

@@ -0,0 +1,147 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { DEFAULT_REQUEST_TIMEOUT_MSEC } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  ListToolsResultSchema,
+  CallToolResultSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { getLogger } from "@/lib/logger";
+
+import {
+  BaseMCPServer,
+  DEFAULT_STREAMABLE_HTTP_MCP_CLIENT_LOGGER_NAME,
+} from "./base";
+import type {
+  MCPTool,
+  CallToolResultContent,
+  MCPServerStreamableHttpOptions,
+  InitializeResult,
+} from "./types";
+
+/**
+ * MCP server client that communicates over streamable HTTP protocol.
+ */
+export class MCPServerStreamableHttp extends BaseMCPServer {
+  readonly id: string;
+  protected session: Client | null = null;
+  protected timeout: number;
+  protected serverInitializeResult: InitializeResult | null = null;
+
+  params: MCPServerStreamableHttpOptions;
+  private transport: any = null;
+
+  constructor(options: MCPServerStreamableHttpOptions) {
+    super({
+      cacheToolsList: options.cacheToolsList,
+      toolFilter: options.toolFilter,
+      logger:
+        options.logger ??
+        getLogger(DEFAULT_STREAMABLE_HTTP_MCP_CLIENT_LOGGER_NAME),
+    });
+
+    this.params = options;
+    this.id = options.id || `streamable-http: ${this.params.url}`;
+    this.timeout = options.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
+  }
+
+  /**
+   * Establishes connection to the MCP server.
+   */
+  async connect(): Promise<void> {
+    try {
+      this.transport = new StreamableHTTPClientTransport(
+        new URL(this.params.url),
+        {
+          authProvider: this.params.authProvider,
+          requestInit: this.params.requestInit,
+          fetch: this.params.fetch,
+          reconnectionOptions: this.params.reconnectionOptions,
+          sessionId: this.params.sessionId,
+        },
+      );
+
+      this.session = new Client({
+        name: this.id,
+        version: "1.0.0",
+      });
+
+      await this.session.connect(this.transport);
+
+      this.serverInitializeResult = {
+        serverInfo: { name: this.id, version: "1.0.0" },
+      } as InitializeResult;
+    } catch (e) {
+      this.logger.error("Error initializing MCP server:", e);
+      await this.close();
+      throw e;
+    }
+
+    this.logger.debug(`Connected to MCP server: ${this.id}`);
+  }
+
+  /**
+   * Closes the connection and cleans up resources.
+   */
+  async close(): Promise<void> {
+    if (this.transport) {
+      await this.transport.close();
+      this.transport = null;
+    }
+    if (this.session) {
+      await this.session.close();
+      this.session = null;
+    }
+  }
+
+  /**
+   * Internal implementation: Fetches tools from the server.
+   *
+   * Cached via the abstract base class.
+   */
+  protected async _listTools(): Promise<MCPTool[]> {
+    if (!this.session) {
+      throw new Error(
+        "Server not initialized. Make sure you call connect() first.",
+      );
+    }
+
+    const response = await this.session.listTools();
+    this.logger.debug(`Listed tools: ${JSON.stringify(response)}`);
+    return ListToolsResultSchema.parse(response).tools;
+  }
+
+  /**
+   * Executes a tool on the server with the provided arguments.
+   */
+  async callTool(
+    toolName: string,
+    args: Record<string, unknown> | null,
+  ): Promise<CallToolResultContent> {
+    if (!this.session) {
+      throw new Error(
+        "Server not initialized. Make sure you call connect() first.",
+      );
+    }
+
+    const response = await this.session.callTool(
+      {
+        name: toolName,
+        arguments: args ?? {},
+      },
+      undefined,
+      {
+        timeout: this.timeout,
+      },
+    );
+
+    const parsed = CallToolResultSchema.parse(response);
+    const result = parsed.content;
+
+    this.logger.debug(
+      `Called tool ${toolName} (args: ${JSON.stringify(args)}, result: ${JSON.stringify(result)})`,
+    );
+
+    return result as CallToolResultContent;
+  }
+}

package/src/mcp/sse.ts

@@ -0,0 +1,137 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { DEFAULT_REQUEST_TIMEOUT_MSEC } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  ListToolsResultSchema,
+  CallToolResultSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { getLogger } from "@/lib/logger";
+
+import { BaseMCPServer, DEFAULT_SSE_MCP_CLIENT_LOGGER_NAME } from "./base";
+import type {
+  MCPTool,
+  CallToolResultContent,
+  MCPServerSSEOptions,
+  InitializeResult,
+} from "./types";
+
+/**
+ * MCP server client that communicates over Server-Sent Events (SSE).
+ */
+export class MCPServerSSE extends BaseMCPServer {
+  readonly id: string;
+  protected session: Client | null = null;
+  protected timeout: number;
+  protected serverInitializeResult: InitializeResult | null = null;
+
+  params: MCPServerSSEOptions;
+  private transport: any = null;
+
+  constructor(options: MCPServerSSEOptions) {
+    super({
+      cacheToolsList: options.cacheToolsList,
+      toolFilter: options.toolFilter,
+      logger: options.logger ?? getLogger(DEFAULT_SSE_MCP_CLIENT_LOGGER_NAME),
+    });
+
+    this.params = options;
+    this.id = options.id || `sse: ${this.params.url}`;
+    this.timeout = options.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
+  }
+
+  /**
+   * Establishes connection to the MCP server.
+   */
+  async connect(): Promise<void> {
+    try {
+      this.transport = new SSEClientTransport(new URL(this.params.url), {
+        authProvider: this.params.authProvider,
+        requestInit: this.params.requestInit,
+        eventSourceInit: this.params.eventSourceInit,
+      });
+
+      this.session = new Client({
+        name: this.id,
+        version: "1.0.0",
+      });
+
+      await this.session.connect(this.transport);
+
+      this.serverInitializeResult = {
+        serverInfo: { name: this.id, version: "1.0.0" },
+      } as InitializeResult;
+    } catch (e) {
+      this.logger.error("Error initializing MCP server:", e);
+      await this.close();
+      throw e;
+    }
+
+    this.logger.debug(`Connected to MCP server: ${this.id}`);
+  }
+
+  /**
+   * Internal implementation: Fetches tools from the server.
+   *
+   * Cached via the BaseMCPServer class.
+   */
+  protected async _listTools(): Promise<MCPTool[]> {
+    if (!this.session) {
+      throw new Error(
+        "Server not initialized. Make sure you call connect() first.",
+      );
+    }
+
+    const response = await this.session.listTools();
+    this.logger.debug(`Listed tools: ${JSON.stringify(response)}`);
+    return ListToolsResultSchema.parse(response).tools;
+  }
+
+  /**
+   * Executes a tool on the server with the provided arguments.
+   */
+  async callTool(
+    toolName: string,
+    args: Record<string, unknown> | null,
+  ): Promise<CallToolResultContent> {
+    if (!this.session) {
+      throw new Error(
+        "Server not initialized. Make sure you call connect() first.",
+      );
+    }
+
+    const response = await this.session.callTool(
+      {
+        name: toolName,
+        arguments: args ?? {},
+      },
+      undefined,
+      {
+        timeout: this.timeout,
+      },
+    );
+
+    const parsed = CallToolResultSchema.parse(response);
+    const result = parsed.content;
+
+    this.logger.debug(
+      `Called tool ${toolName} (args: ${JSON.stringify(args)}, result: ${JSON.stringify(result)})`,
+    );
+
+    return result as CallToolResultContent;
+  }
+
+  /**
+   * Closes the connection and cleans up resources.
+   */
+  async close(): Promise<void> {
+    if (this.transport) {
+      await this.transport.close();
+      this.transport = null;
+    }
+    if (this.session) {
+      await this.session.close();
+      this.session = null;
+    }
+  }
+}

package/src/mcp/stdio.ts

@@ -0,0 +1,136 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { DEFAULT_REQUEST_TIMEOUT_MSEC } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  ListToolsResultSchema,
+  CallToolResultSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { getLogger } from "@/lib/logger";
+
+import { BaseMCPServer, DEFAULT_STDIO_MCP_CLIENT_LOGGER_NAME } from "./base";
+import type {
+  MCPTool,
+  CallToolResultContent,
+  MCPServerStdioOptions,
+  InitializeResult,
+} from "./types";
+
+/**
+ * MCP server client that communicates over stdio (standard input/output).
+ */
+export class MCPServerStdio extends BaseMCPServer {
+  readonly id: string;
+  protected session: Client | null = null;
+  protected timeout: number;
+  protected serverInitializeResult: InitializeResult | null = null;
+
+  private params: MCPServerStdioOptions;
+  private transport: any = null;
+
+  constructor(options: MCPServerStdioOptions) {
+    super({
+      cacheToolsList: options.cacheToolsList,
+      toolFilter: options.toolFilter,
+      logger: options.logger ?? getLogger(DEFAULT_STDIO_MCP_CLIENT_LOGGER_NAME),
+    });
+
+    this.timeout = options.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
+    this.params = options;
+    this.id = options.id || `stdio: ${this.params.command}`;
+  }
+
+  /**
+   * Establishes connection to the MCP server.
+   */
+  async connect(): Promise<void> {
+    try {
+      this.transport = new StdioClientTransport({
+        command: this.params.command,
+        args: this.params.args,
+        env: this.params.env,
+        cwd: this.params.cwd,
+      });
+
+      this.session = new Client({
+        name: this.id,
+        version: "1.0.0",
+      });
+
+      await this.session.connect(this.transport);
+
+      this.serverInitializeResult = {
+        serverInfo: { name: this.id, version: "1.0.0" },
+      } as InitializeResult;
+
+      this.logger.debug(`Connected to MCP server: ${this.id}`);
+    } catch (e) {
+      this.logger.error("Error initializing MCP server:", e);
+      await this.close();
+      throw e;
+    }
+  }
+
+  /**
+   * Internal implementation: Fetches tools from the server.
+   */
+  protected async _listTools(): Promise<MCPTool[]> {
+    if (!this.session) {
+      throw new Error(
+        "Server not initialized. Make sure you call connect() first.",
+      );
+    }
+
+    const response = await this.session.listTools();
+    this.logger.debug(`Listed tools: ${JSON.stringify(response)}`);
+    return ListToolsResultSchema.parse(response).tools;
+  }
+
+  /**
+   * Executes a tool on the server with the provided arguments.
+   */
+  async callTool(
+    toolName: string,
+    args: Record<string, unknown> | null,
+  ): Promise<CallToolResultContent> {
+    if (!this.session) {
+      throw new Error(
+        "Server not initialized. Make sure you call connect() first.",
+      );
+    }
+
+    const response = await this.session.callTool(
+      {
+        name: toolName,
+        arguments: args ?? {},
+      },
+      undefined,
+      {
+        timeout: this.timeout,
+      },
+    );
+
+    const parsed = CallToolResultSchema.parse(response);
+    const result = parsed.content;
+
+    this.logger.debug(
+      `Called tool ${toolName} (args: ${JSON.stringify(args)}, result: ${JSON.stringify(result)})`,
+    );
+
+    return result as CallToolResultContent;
+  }
+
+  /**
+   * Closes the connection and cleans up resources.
+   */
+  async close(): Promise<void> {
+    if (this.transport) {
+      await this.transport.close();
+      this.transport = null;
+    }
+    if (this.session) {
+      await this.session.close();
+      this.session = null;
+    }
+  }
+}