@mozilla-ai/mcpd 0.0.3 → 0.1.0

package/dist/index.mjs

@@ -1,5 +1,7 @@
 import { LRUCache } from "lru-cache";
 import { z } from "zod";
+const PIPELINE_FLOW_REQUEST = "request";
+const PIPELINE_FLOW_RESPONSE = "response";
 class McpdError extends Error {
   constructor(message, cause) {
     super(message);
@@ -86,6 +88,19 @@ class TimeoutError extends McpdError {
     Error.captureStackTrace(this, this.constructor);
   }
 }
+class PipelineError extends McpdError {
+  serverName;
+  operation;
+  pipelineFlow;
+  constructor(message, serverName, operation, pipelineFlow, cause) {
+    super(message, cause);
+    this.name = "PipelineError";
+    this.serverName = serverName;
+    this.operation = operation;
+    this.pipelineFlow = pipelineFlow;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
 var HealthStatus = /* @__PURE__ */ ((HealthStatus2) => {
   HealthStatus2["OK"] = "ok";
   HealthStatus2["TIMEOUT"] = "timeout";
@@ -941,6 +956,14 @@ class FunctionBuilder {
   getCacheSize() {
     return this.#functionCache.size;
   }
+  /**
+   * Get all cached functions.
+   *
+   * @returns Array of all cached agent functions, or empty array if cache is empty
+   */
+  getCachedFunctions() {
+    return Array.from(this.#functionCache.values());
+  }
 }
 const API_BASE = "/api/v1";
 const SERVERS_BASE = `${API_BASE}/servers`;
@@ -971,13 +994,81 @@ const API_PATHS = {
   HEALTH_ALL: HEALTH_SERVERS_BASE,
   HEALTH_SERVER: (serverName) => `${HEALTH_SERVERS_BASE}/${encodeURIComponent(serverName)}`
 };
+const LogLevels = {
+  OFF: "off"
+};
+const ranks = {
+  trace: 5,
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  off: 1e3
+};
+function resolve(raw) {
+  const candidate = raw?.toLowerCase();
+  return candidate && candidate in ranks ? candidate : LogLevels.OFF;
+}
+function getLevel() {
+  return resolve(
+    typeof process !== "undefined" ? process.env.MCPD_LOG_LEVEL : void 0
+  );
+}
+function defaultLogger() {
+  return {
+    trace: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== LogLevels.OFF && ranks[lvl] <= ranks.trace)
+        console.trace(...args);
+    },
+    debug: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== LogLevels.OFF && ranks[lvl] <= ranks.debug)
+        console.debug(...args);
+    },
+    info: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== LogLevels.OFF && ranks[lvl] <= ranks.info)
+        console.info(...args);
+    },
+    warn: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== LogLevels.OFF && ranks[lvl] <= ranks.warn)
+        console.warn(...args);
+    },
+    error: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== LogLevels.OFF && ranks[lvl] <= ranks.error)
+        console.error(...args);
+    }
+  };
+}
+function createLogger(impl) {
+  const base = defaultLogger();
+  return {
+    trace: impl?.trace ?? base.trace,
+    debug: impl?.debug ?? base.debug,
+    info: impl?.info ?? base.info,
+    warn: impl?.warn ?? base.warn,
+    error: impl?.error ?? base.error
+  };
+}
+const REQUEST_TIMEOUT_SECONDS = 30;
+const SERVER_HEALTH_CACHE_TTL_SECONDS = 10;
 const SERVER_HEALTH_CACHE_MAXSIZE = 100;
+const TOOL_SEPARATOR = "__";
+const MCPD_ERROR_TYPE_HEADER = "Mcpd-Error-Type";
+const PIPELINE_ERROR_FLOWS = {
+  "request-pipeline-failure": PIPELINE_FLOW_REQUEST,
+  "response-pipeline-failure": PIPELINE_FLOW_RESPONSE
+};
 class McpdClient {
   #endpoint;
   #apiKey;
   #timeout;
   #serverHealthCache;
   #functionBuilder;
+  #logger;
   #cacheableExceptions = /* @__PURE__ */ new Set([
     ServerNotFoundError,
     ServerUnhealthyError,
@@ -993,14 +1084,18 @@ class McpdClient {
    * @param options - Configuration options for the client
    */
   constructor(options) {
+    const toMs = (s) => s * 1e3;
     this.#endpoint = options.apiEndpoint.replace(/\/$/, "");
     this.#apiKey = options.apiKey;
-    this.#timeout = options.timeout ?? 3e4;
-    const healthCacheTtlMs = (options.healthCacheTtl ?? 10) * 1e3;
+    this.#timeout = options.timeout ?? toMs(REQUEST_TIMEOUT_SECONDS);
+    const healthCacheTtlMs = toMs(
+      options.healthCacheTtl ?? SERVER_HEALTH_CACHE_TTL_SECONDS
+    );
     this.#serverHealthCache = createCache({
       max: SERVER_HEALTH_CACHE_MAXSIZE,
       ttl: healthCacheTtlMs
     });
+    this.#logger = createLogger(options.logger);
     this.servers = new ServersNamespace({
       performCall: this.#performCall.bind(this),
       getTools: this.#getToolsByServer.bind(this),
@@ -1017,8 +1112,15 @@ class McpdClient {
    *
    * @param path - The API path (e.g., '/servers', '/servers/{server_name}/tools')
    * @param options - Request options
+   *
    * @returns The JSON response from the daemon
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
+   * @throws {ConnectionError} If unable to connect to the mcpd daemon
+   * @throws {TimeoutError} If the request times out
    * @throws {McpdError} If the request fails
+   *
+   * @internal
    */
   async #request(path, options = {}) {
     const url = `${this.#endpoint}${path}`;
@@ -1046,6 +1148,21 @@ class McpdClient {
         } catch {
           errorModel = null;
         }
+        if (response.status === 500) {
+          const errorType = response.headers.get(MCPD_ERROR_TYPE_HEADER)?.toLowerCase();
+          const flow = errorType ? PIPELINE_ERROR_FLOWS[errorType] : void 0;
+          if (flow) {
+            const message = errorModel?.detail || body || "Pipeline failure";
+            throw new PipelineError(
+              message,
+              void 0,
+              // serverName - enriched by caller if available.
+              void 0,
+              // operation - enriched by caller if available.
+              flow
+            );
+          }
+        }
         if (errorModel && errorModel.detail) {
           const errorDetails = errorModel.errors?.map((e) => `${e.location}: ${e.message}`).join("; ");
           const fullMessage = errorDetails ? `${errorModel.detail} - ${errorDetails}` : errorModel.detail;
@@ -1098,6 +1215,10 @@ class McpdClient {
    * Get a list of all configured MCP servers.
    *
    * @returns Array of server names
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
+   * @throws {ConnectionError} If unable to connect to the mcpd daemon
+   * @throws {TimeoutError} If the request times out
    * @throws {McpdError} If the request fails
    *
    * @example
@@ -1110,16 +1231,23 @@ class McpdClient {
     return await this.#request(API_PATHS.SERVERS);
   }
   /**
-   * Internal method to get tool schemas for a server.
+   * Get tool schemas for a server.
+   *
+   * @privateRemarks
    * Used by dependency injection for ServersNamespace and internally for getAgentTools.
    *
    * @param serverName - Server name to get tools for
+   *
    * @returns Tool schemas for the specified server
+   *
    * @throws {ServerNotFoundError} If the specified server doesn't exist
    * @throws {ServerUnhealthyError} If the server is not healthy
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
    * @throws {ConnectionError} If unable to connect to the mcpd daemon
    * @throws {TimeoutError} If the request times out
    * @throws {McpdError} If the request fails
+   *
    * @internal
    */
   async #getToolsByServer(serverName) {
@@ -1135,17 +1263,24 @@ class McpdClient {
     return response.tools;
   }
   /**
-   * Internal method to get prompt schemas for a server.
+   * Get prompt schemas for a server.
+   *
+   * @privateRemarks
    * Used internally for getPromptSchemas.
    *
    * @param serverName - Server name to get prompts for
-   * @param cursor - Optional cursor for pagination
+   * @param cursor - Cursor for pagination
+   *
    * @returns Prompt schemas for the specified server
+   *
    * @throws {ServerNotFoundError} If the specified server doesn't exist
    * @throws {ServerUnhealthyError} If the server is not healthy
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
    * @throws {ConnectionError} If unable to connect to the mcpd daemon
    * @throws {TimeoutError} If the request times out
    * @throws {McpdError} If the request fails
+   *
    * @internal
    */
   async #getPromptsByServer(serverName, cursor) {
@@ -1162,16 +1297,24 @@ class McpdClient {
     }
   }
   /**
-   * Internal method to generate a prompt on a server.
+   * Generate a prompt on a server.
    *
-   * This method is used internally by:
+   * @privateRemarks
+   * Used internally by:
    * - PromptsNamespace (via dependency injection)
    * - Server.generatePrompt() (via dependency injection)
    *
    * @param serverName - The name of the server
    * @param promptName - The exact name of the prompt
    * @param args - The prompt arguments
+   *
    * @returns The generated prompt response
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
+   * @throws {ConnectionError} If unable to connect to the mcpd daemon
+   * @throws {TimeoutError} If the request times out
+   * @throws {McpdError} If the request fails
+   *
    * @internal
    */
   async #generatePromptInternal(serverName, promptName, args) {
@@ -1187,17 +1330,24 @@ class McpdClient {
     return response;
   }
   /**
-   * Internal method to get resource schemas for a server.
+   * Get resource schemas for a server.
+   *
+   * @privateRemarks
    * Used internally for getResources and by dependency injection for ServersNamespace.
    *
    * @param serverName - Server name to get resources for
-   * @param cursor - Optional cursor for pagination
+   * @param cursor - Cursor for pagination
+   *
    * @returns Resource schemas for the specified server
+   *
    * @throws {ServerNotFoundError} If the specified server doesn't exist
    * @throws {ServerUnhealthyError} If the server is not healthy
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
    * @throws {ConnectionError} If unable to connect to the mcpd daemon
    * @throws {TimeoutError} If the request times out
    * @throws {McpdError} If the request fails
+   *
    * @internal
    */
   async #getResourcesByServer(serverName, cursor) {
@@ -1214,17 +1364,24 @@ class McpdClient {
     }
   }
   /**
-   * Internal method to get resource template schemas for a server.
+   * Get resource template schemas for a server.
+   *
+   * @privateRemarks
    * Used internally for getResourceTemplates and by dependency injection for ServersNamespace.
    *
    * @param serverName - Server name to get resource templates for
-   * @param cursor - Optional cursor for pagination
+   * @param cursor - Cursor for pagination
+   *
    * @returns Resource template schemas for the specified server
+   *
    * @throws {ServerNotFoundError} If the specified server doesn't exist
    * @throws {ServerUnhealthyError} If the server is not healthy
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
    * @throws {ConnectionError} If unable to connect to the mcpd daemon
    * @throws {TimeoutError} If the request times out
    * @throws {McpdError} If the request fails
+   *
    * @internal
    */
   async #getResourceTemplatesByServer(serverName, cursor) {
@@ -1241,17 +1398,24 @@ class McpdClient {
     }
   }
   /**
-   * Internal method to read resource content from a server.
+   * Read resource content from a server.
+   *
+   * @privateRemarks
    * Used by dependency injection for ServersNamespace.
    *
    * @param serverName - Server name to read resource from
    * @param uri - The resource URI
+   *
    * @returns Array of resource contents (text or blob)
+   *
    * @throws {ServerNotFoundError} If the specified server doesn't exist
    * @throws {ServerUnhealthyError} If the server is not healthy
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
    * @throws {ConnectionError} If unable to connect to the mcpd daemon
    * @throws {TimeoutError} If the request times out
    * @throws {McpdError} If the request fails
+   *
    * @internal
    */
   async #readResourceByServer(serverName, uri) {
@@ -1303,8 +1467,14 @@ class McpdClient {
    * Check if a specific server is healthy.
    *
    * @param serverName - The name of the server to check
+   *
    * @returns True if the server is healthy, false otherwise
    *
+   * @throws {AuthenticationError} If API key was present and authentication fails
+   * @throws {ConnectionError} If unable to connect to the mcpd daemon
+   * @throws {TimeoutError} If the request times out
+   * @throws {McpdError} If the request fails
+   *
    * @example
    * ```typescript
    * if (await client.isServerHealthy('time')) {
@@ -1327,8 +1497,14 @@ class McpdClient {
    * Ensure a server is healthy before performing an operation.
    *
    * @param serverName - The name of the server to check
+   *
    * @throws {ServerNotFoundError} If the server doesn't exist
    * @throws {ServerUnhealthyError} If the server is not healthy
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
+   * @throws {ConnectionError} If unable to connect to the mcpd daemon
+   * @throws {TimeoutError} If the request times out
+   * @throws {McpdError} If the request fails
    */
   async #ensureServerHealthy(serverName) {
     const health = await this.getServerHealth(serverName);
@@ -1347,35 +1523,60 @@ class McpdClient {
     }
   }
   /**
-   * Get list of healthy servers from optional server names.
+   * Get list of healthy servers.
    *
-   * This helper fetches server names (if not provided) and filters to only healthy servers.
-   * Used by getToolSchemas(), getPrompts(), and agentTools() to avoid timeouts on failed servers.
+   * @remarks
+   * If logging is enabled, warnings are logged for servers that do not exist or are unhealthy.
    *
-   * @param servers - Optional array of server names. If not provided, fetches all servers.
-   * @returns Array of healthy server names
-   * @internal
+   * @param servers - List of server names to use for health checking.
+   *                  If not provided, or empty, checks health for all servers.
+   *
+   * @returns List of server names with 'ok' health status.
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
+   * @throws {ConnectionError} If unable to connect to the mcpd daemon
+   * @throws {TimeoutError} If the request times out
+   * @throws {McpdError} If the request fails
    */
   async #getHealthyServers(servers) {
-    const serverNames = servers && servers.length > 0 ? servers : await this.listServers();
+    const serverNames = servers?.length ? servers : await this.listServers();
     const healthMap = await this.getServerHealth();
     return serverNames.filter((name) => {
       const health = healthMap[name];
-      return health && HealthStatusHelpers.isHealthy(health.status);
+      if (!health) {
+        this.#logger.warn(`Skipping non-existent server '${name}'`);
+        return false;
+      }
+      if (!HealthStatusHelpers.isHealthy(health.status)) {
+        this.#logger.warn(
+          `Skipping unhealthy server '${name}' with status '${health.status}'`
+        );
+        return false;
+      }
+      return true;
     });
   }
   /**
-   * Internal method to perform a tool call on a server.
+   * Perform a tool call on a server.
    *
-   * This method is used internally by:
+   * @privateRemarks
+   * Used internally by:
    * - ToolsNamespace (via dependency injection)
    * - FunctionBuilder (via dependency injection)
    *
    * @param serverName - The name of the server
    * @param toolName - The exact name of the tool
    * @param args - The tool arguments
+   *
    * @returns The tool's response
+   *
    * @throws {ToolExecutionError} If the tool execution fails
+   *
+   * @throws {AuthenticationError} If API key was present and authentication fails
+   * @throws {ConnectionError} If unable to connect to the mcpd daemon
+   * @throws {TimeoutError} If the request times out
+   * @throws {McpdError} If the request fails
+   *
    * @internal
    */
   async #performCall(serverName, toolName, args) {
@@ -1394,6 +1595,15 @@ class McpdClient {
       }
       return response;
     } catch (error) {
+      if (error instanceof PipelineError) {
+        throw new PipelineError(
+          error.message,
+          serverName,
+          `${serverName}.${toolName}`,
+          error.pipelineFlow,
+          error.cause
+        );
+      }
       if (error instanceof McpdError) {
         throw error;
       }
@@ -1421,29 +1631,33 @@ class McpdClient {
     this.#serverHealthCache.clear();
   }
   /**
-   * Generate callable functions for use with AI agent frameworks (internal).
+   * Fetch and cache callable functions from all healthy servers.
    *
-   * This method queries servers and creates self-contained, callable functions
+   * This method queries all healthy servers and creates self-contained, callable functions
    * that can be passed to AI agent frameworks. Each function includes its schema
    * as metadata and handles the MCP communication internally.
    *
-   * This method automatically filters out unhealthy servers by checking their health
-   * status before fetching tools. Unhealthy servers are silently skipped to ensure
-   * the method returns quickly without waiting for timeouts on failed servers.
+   * Unhealthy servers are automatically filtered out and skipped (with optional warnings
+   * when logging is enabled) to ensure the method returns quickly without waiting for timeouts.
    *
    * Tool fetches from multiple servers are executed concurrently for optimal performance.
+   * Functions are cached indefinitely until explicitly cleared.
    *
-   * @param servers - Optional list of server names to include. If not specified, includes all servers.
-   * @returns Array of callable functions with metadata. Only includes tools from healthy servers.
+   * @returns Array of callable functions with metadata from all healthy servers.
    *
+   * @throws {AuthenticationError} If API key was present and authentication fails
    * @throws {ConnectionError} If unable to connect to the mcpd daemon
-   * @throws {TimeoutError} If requests to the daemon time out
-   * @throws {AuthenticationError} If API key authentication fails
-   * @throws {McpdError} If unable to retrieve health status, server list, or generate functions
+   * @throws {TimeoutError} If the request times out
+   * @throws {McpdError} If the request fails
+   *
    * @internal
    */
-  async agentTools(servers) {
-    const healthyServers = await this.#getHealthyServers(servers);
+  async #agentTools() {
+    const cachedFunctions = this.#functionBuilder.getCachedFunctions();
+    if (cachedFunctions.length > 0) {
+      return cachedFunctions;
+    }
+    const healthyServers = await this.#getHealthyServers();
     const results = await Promise.allSettled(
       healthyServers.map(async (serverName) => ({
         serverName,
@@ -1462,17 +1676,43 @@ class McpdClient {
     return agentTools;
   }
   async getAgentTools(options = {}) {
-    const { servers, format = "array" } = options;
-    const tools = await this.agentTools(servers);
-    switch (format) {
-      case "object":
-        return Object.fromEntries(tools.map((tool) => [tool.name, tool]));
-      case "map":
-        return new Map(tools.map((tool) => [tool.name, tool]));
-      case "array":
-      default:
-        return tools;
-    }
+    const { servers, tools, format = "array", refreshCache = false } = options;
+    if (refreshCache) this.#functionBuilder.clearCache();
+    const allTools = await this.#agentTools();
+    const filteredTools = allTools.filter((tool) => !servers || servers.includes(tool._serverName)).filter((tool) => !tools || this.#matchesToolFilter(tool, tools));
+    const formatters = {
+      array: (t) => t,
+      object: (t) => Object.fromEntries(t.map((tool) => [tool.name, tool])),
+      map: (t) => new Map(t.map((tool) => [tool.name, tool]))
+    };
+    return formatters[format](filteredTools);
+  }
+  /**
+   * Check if a tool matches the tool filter.
+   *
+   * Supports two formats:
+   * - Raw tool name: "get_current_time" (matches across all servers)
+   * - Server-prefixed: "time__get_current_time" (matches specific server + tool)
+   *
+   * @remarks
+   * When a filter contains "__", it's first checked as server-prefixed (exact match).
+   * If that fails, it's checked as a raw tool name. This handles tools whose names
+   * contain "__" (e.g., "my__special__tool").
+   *
+   * @param tool The tool to match.
+   * @param tools List of tool names to match against.
+   *
+   * @returns True if a match is found in tools, based on the predicate.
+   *
+   * @internal
+   */
+  #matchesToolFilter(tool, tools) {
+    return tools.some((filterItem) => {
+      if (filterItem.indexOf(TOOL_SEPARATOR) === -1) {
+        return filterItem === tool._toolName;
+      }
+      return filterItem === tool.name || filterItem === tool._toolName;
+    });
   }
 }
 export {
@@ -1482,6 +1722,9 @@ export {
   HealthStatusHelpers,
   McpdClient,
   McpdError,
+  PIPELINE_FLOW_REQUEST,
+  PIPELINE_FLOW_RESPONSE,
+  PipelineError,
   ServerNotFoundError,
   ServerUnhealthyError,
   TimeoutError,