@mozilla-ai/mcpd 0.0.1

package/dist/index.mjs

@@ -0,0 +1,1130 @@
+import { LRUCache } from "lru-cache";
+import { z } from "zod";
+class McpdError extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = "McpdError";
+    this.cause = cause;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+class ConnectionError extends McpdError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "ConnectionError";
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+class AuthenticationError extends McpdError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "AuthenticationError";
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+class ServerNotFoundError extends McpdError {
+  serverName;
+  constructor(message, serverName, cause) {
+    super(message, cause);
+    this.name = "ServerNotFoundError";
+    this.serverName = serverName;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+class ServerUnhealthyError extends McpdError {
+  serverName;
+  healthStatus;
+  constructor(message, serverName, healthStatus, cause) {
+    super(message, cause);
+    this.name = "ServerUnhealthyError";
+    this.serverName = serverName;
+    this.healthStatus = healthStatus;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+class ToolNotFoundError extends McpdError {
+  serverName;
+  toolName;
+  constructor(message, serverName, toolName, cause) {
+    super(message, cause);
+    this.name = "ToolNotFoundError";
+    this.serverName = serverName;
+    this.toolName = toolName;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+class ToolExecutionError extends McpdError {
+  serverName;
+  toolName;
+  errorModel;
+  constructor(message, serverName, toolName, errorModel, cause) {
+    super(message, cause);
+    this.name = "ToolExecutionError";
+    this.serverName = serverName;
+    this.toolName = toolName;
+    this.errorModel = errorModel;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+class ValidationError extends McpdError {
+  validationErrors;
+  constructor(message, validationErrors, cause) {
+    super(message, cause);
+    this.name = "ValidationError";
+    this.validationErrors = validationErrors || [];
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+class TimeoutError extends McpdError {
+  operation;
+  timeout;
+  constructor(message, operation, timeout, cause) {
+    super(message, cause);
+    this.name = "TimeoutError";
+    this.operation = operation;
+    this.timeout = timeout;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+var HealthStatus = /* @__PURE__ */ ((HealthStatus2) => {
+  HealthStatus2["OK"] = "ok";
+  HealthStatus2["TIMEOUT"] = "timeout";
+  HealthStatus2["UNREACHABLE"] = "unreachable";
+  HealthStatus2["UNKNOWN"] = "unknown";
+  return HealthStatus2;
+})(HealthStatus || {});
+const HealthStatusHelpers = {
+  /**
+   * Check if the given health status is a transient error state.
+   */
+  isTransient(status) {
+    return status === "timeout" || status === "unknown";
+  },
+  /**
+   * Check if the given status string represents a healthy state.
+   */
+  isHealthy(status) {
+    return status === "ok";
+  }
+};
+function createCache(options = {}) {
+  return new LRUCache({
+    max: options.max ?? 100,
+    ttl: options.ttl ?? 1e4,
+    // Default 10 seconds
+    updateAgeOnGet: false,
+    updateAgeOnHas: false
+  });
+}
+class ServersNamespace {
+  #performCall;
+  #getTools;
+  /**
+   * Initialize the ServersNamespace with injected functions.
+   *
+   * @param performCall - Function to execute tool calls
+   * @param getTools - Function to get tool schemas
+   */
+  constructor(performCall, getTools) {
+    this.#performCall = performCall;
+    this.#getTools = getTools;
+    return new Proxy(this, {
+      get: (target, serverName) => {
+        if (typeof serverName !== "string") {
+          return void 0;
+        }
+        return new Server(target.#performCall, target.#getTools, serverName);
+      }
+    });
+  }
+}
+class Server {
+  tools;
+  #performCall;
+  #getTools;
+  #serverName;
+  /**
+   * Initialize a Server for a specific server.
+   *
+   * @param performCall - Function to execute tool calls
+   * @param getTools - Function to get tool schemas
+   * @param serverName - The name of the MCP server
+   */
+  constructor(performCall, getTools, serverName) {
+    this.#performCall = performCall;
+    this.#getTools = getTools;
+    this.#serverName = serverName;
+    this.tools = new ToolsNamespace(
+      this.#performCall,
+      this.#getTools,
+      this.#serverName
+    );
+  }
+  /**
+   * List all tools available on this server.
+   *
+   * @returns Array of tool schemas
+   * @throws {ServerNotFoundError} If the server doesn't exist
+   * @throws {ServerUnhealthyError} If the server is unhealthy
+   *
+   * @example
+   * ```typescript
+   * const tools = await client.servers.time.listTools();
+   * for (const tool of tools) {
+   *   console.log(`${tool.name}: ${tool.description}`);
+   * }
+   * ```
+   */
+  async listTools() {
+    return this.#getTools(this.#serverName);
+  }
+  /**
+   * Check if a tool exists on this server.
+   *
+   * The tool name must match exactly as returned by the server.
+   *
+   * @param toolName - The exact name of the tool to check
+   * @returns True if the tool exists, false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (await client.servers.time.hasTool('get_current_time')) {
+   *   const result = await client.servers.time.callTool('get_current_time', { timezone: 'UTC' });
+   * }
+   * ```
+   */
+  async hasTool(toolName) {
+    try {
+      const tools = await this.#getTools(this.#serverName);
+      return tools.some((t) => t.name === toolName);
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Call a tool by name with the given arguments.
+   *
+   * This method is useful for programmatic tool invocation when the tool name
+   * is in a variable. The tool name must match exactly as returned by the server.
+   *
+   * @param toolName - The exact name of the tool to call
+   * @param args - The arguments to pass to the tool
+   * @returns The tool's response
+   * @throws {ToolNotFoundError} If the tool doesn't exist on the server
+   *
+   * @example
+   * ```typescript
+   * // Call with explicit method (useful for dynamic tool names):
+   * const toolName = 'get_current_time';
+   * await client.servers.time.callTool(toolName, { timezone: 'UTC' });
+   *
+   * // Or with dynamic server name:
+   * const serverName = 'time';
+   * await client.servers[serverName].callTool(toolName, { timezone: 'UTC' });
+   * ```
+   */
+  async callTool(toolName, args) {
+    const tools = await this.#getTools(this.#serverName);
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+      throw new ToolNotFoundError(
+        `Tool '${toolName}' not found on server '${this.#serverName}'. Use client.servers.${this.#serverName}.listTools() to see available tools.`,
+        this.#serverName,
+        toolName
+      );
+    }
+    return this.#performCall(this.#serverName, toolName, args);
+  }
+}
+class ToolsNamespace {
+  #performCall;
+  #getTools;
+  #serverName;
+  /**
+   * Initialize a ToolsNamespace for a specific server.
+   *
+   * @param performCall - Function to execute tool calls
+   * @param getTools - Function to get tool schemas
+   * @param serverName - The name of the MCP server
+   */
+  constructor(performCall, getTools, serverName) {
+    this.#performCall = performCall;
+    this.#getTools = getTools;
+    this.#serverName = serverName;
+    return new Proxy(this, {
+      get: (target, prop) => {
+        if (typeof prop !== "string") {
+          return void 0;
+        }
+        return async (args) => {
+          const toolName = prop;
+          const tools = await target.#getTools(target.#serverName);
+          const tool = tools.find((t) => t.name === toolName);
+          if (!tool) {
+            throw new ToolNotFoundError(
+              `Tool '${toolName}' not found on server '${target.#serverName}'. Use client.servers.${target.#serverName}.listTools() to see available tools.`,
+              target.#serverName,
+              toolName
+            );
+          }
+          return target.#performCall(target.#serverName, toolName, args);
+        };
+      }
+    });
+  }
+}
+class TypeConverter {
+  /**
+   * Convert JSON schema types to JavaScript type names.
+   *
+   * Maps JSON Schema types to their JavaScript equivalents:
+   * - "string" → "string"
+   * - "integer" → "number"
+   * - "number" → "number"
+   * - "boolean" → "boolean"
+   * - "array" → "array"
+   * - "object" → "object"
+   * - "null" → "null"
+   * - unknown types → "any"
+   */
+  static jsonTypeToJavaScriptType(jsonType, schemaDef) {
+    switch (jsonType) {
+      case "string":
+        if (schemaDef.enum && Array.isArray(schemaDef.enum)) {
+          return "string";
+        }
+        return "string";
+      case "number":
+      case "integer":
+        return "number";
+      case "boolean":
+        return "boolean";
+      case "array":
+        return "array";
+      case "object":
+        return "object";
+      case "null":
+        return "null";
+      default:
+        return "any";
+    }
+  }
+  /**
+   * Parse a schema definition and return the appropriate JavaScript type name.
+   */
+  static parseSchemaType(schemaDef) {
+    if (schemaDef.anyOf && Array.isArray(schemaDef.anyOf)) {
+      const firstType = schemaDef.anyOf[0];
+      if (firstType && typeof firstType === "object" && firstType.type) {
+        return this.jsonTypeToJavaScriptType(firstType.type, firstType);
+      }
+      return "any";
+    }
+    if (schemaDef.type) {
+      return this.jsonTypeToJavaScriptType(schemaDef.type, schemaDef);
+    }
+    return "any";
+  }
+  /**
+   * Get a human-readable description of the expected type.
+   */
+  static getTypeDescription(schemaDef) {
+    const baseType = this.parseSchemaType(schemaDef);
+    if (schemaDef.enum && Array.isArray(schemaDef.enum)) {
+      return `one of: ${schemaDef.enum.map((v) => JSON.stringify(v)).join(", ")}`;
+    }
+    if (schemaDef.type === "array" && schemaDef.items) {
+      const itemType = this.parseSchemaType(schemaDef.items);
+      return `array of ${itemType}`;
+    }
+    return baseType;
+  }
+  /**
+   * Validate a value against a JSON schema type.
+   * Returns true if valid, false otherwise.
+   */
+  static validateValue(value, schemaDef) {
+    if (value === null || value === void 0) {
+      return schemaDef.type === "null" || (schemaDef.anyOf?.some((s) => s.type === "null") ?? false);
+    }
+    if (schemaDef.enum && Array.isArray(schemaDef.enum)) {
+      return schemaDef.enum.includes(value);
+    }
+    if (schemaDef.anyOf && Array.isArray(schemaDef.anyOf)) {
+      return schemaDef.anyOf.some(
+        (subSchema) => this.validateValue(value, subSchema)
+      );
+    }
+    if (!schemaDef.type) {
+      return true;
+    }
+    switch (schemaDef.type) {
+      case "string":
+        return typeof value === "string";
+      case "number":
+        return typeof value === "number" && isFinite(value);
+      case "integer":
+        return typeof value === "number" && Number.isInteger(value);
+      case "boolean":
+        return typeof value === "boolean";
+      case "array":
+        if (!Array.isArray(value)) return false;
+        if (schemaDef.items) {
+          return value.every(
+            (item) => this.validateValue(item, schemaDef.items)
+          );
+        }
+        return true;
+      case "object":
+        return typeof value === "object" && value !== null && !Array.isArray(value);
+      case "null":
+        return value === null;
+      default:
+        return true;
+    }
+  }
+}
+class FunctionBuilder {
+  #performCall;
+  #functionCache = /* @__PURE__ */ new Map();
+  /**
+   * Initialize a FunctionBuilder with an injected function.
+   *
+   * @param performCall - Function to execute tool calls
+   */
+  constructor(performCall) {
+    this.#performCall = performCall;
+  }
+  /**
+   * Convert JSON schema to Zod schema.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  #jsonSchemaToZod(jsonSchema) {
+    if (!jsonSchema || typeof jsonSchema !== "object") {
+      return z.object({});
+    }
+    switch (jsonSchema.type) {
+      case "string":
+        return z.string();
+      case "number":
+        return z.number();
+      case "integer":
+        return z.number().int();
+      case "boolean":
+        return z.boolean();
+      case "array":
+        return z.array(
+          jsonSchema.items ? this.#jsonSchemaToZod(jsonSchema.items) : z.any()
+        );
+      case "object":
+        if (jsonSchema.properties) {
+          const propertyKeys = Object.keys(jsonSchema.properties);
+          if (propertyKeys.length > 0) {
+            const shape = {};
+            const required = new Set(jsonSchema.required || []);
+            for (const [key, value] of Object.entries(jsonSchema.properties)) {
+              let schema = this.#jsonSchemaToZod(value);
+              if (!required.has(key)) {
+                schema = schema.nullable().optional();
+              }
+              shape[key] = schema;
+            }
+            return z.object(shape);
+          }
+        }
+        return z.object({});
+      default:
+        if (jsonSchema.properties) {
+          const propertyKeys = Object.keys(jsonSchema.properties);
+          if (propertyKeys.length > 0) {
+            const shape = {};
+            const required = new Set(jsonSchema.required || []);
+            for (const [key, value] of Object.entries(jsonSchema.properties)) {
+              let schema = this.#jsonSchemaToZod(value);
+              if (!required.has(key)) {
+                schema = schema.nullable().optional();
+              }
+              shape[key] = schema;
+            }
+            return z.object(shape);
+          }
+        }
+        return z.object({});
+    }
+  }
+  /**
+   * Convert a string into a safe JavaScript identifier.
+   *
+   * This method sanitizes arbitrary strings (like server names or tool names) to create
+   * valid JavaScript identifiers that can be used as function names.
+   * It replaces non-word characters and handles edge cases like leading digits.
+   *
+   * @param name - The string to convert into a safe identifier
+   * @returns A string that is a valid JavaScript identifier
+   */
+  safeName(name) {
+    return name.replace(/\W|^(?=\d)/g, "_");
+  }
+  /**
+   * Generate a unique function name from server and tool names.
+   *
+   * This method creates a qualified function name by combining the server name
+   * and tool name with a double underscore separator. Both names are sanitized
+   * using safeName() to ensure the result is a valid JavaScript identifier.
+   *
+   * @param serverName - The name of the MCP server hosting the tool
+   * @param schemaName - The name of the tool from the schema definition
+   * @returns A qualified function name in the format "{safe_server}__{safe_tool}"
+   */
+  functionName(serverName, schemaName) {
+    return `${this.safeName(serverName)}__${this.safeName(schemaName)}`;
+  }
+  /**
+   * Create a callable JavaScript function from an MCP tool's JSON Schema definition.
+   *
+   * This method generates a self-contained, callable function that validates parameters
+   * and executes the corresponding MCP tool. The function includes proper parameter
+   * validation and comprehensive metadata based on the tool's JSON Schema.
+   *
+   * Generated functions are cached for performance. If a function for the same
+   * server/tool combination already exists in the cache, it returns the cached function.
+   *
+   * @param schema - The MCP tool's JSON Schema definition
+   * @param serverName - The name of the MCP server hosting this tool
+   * @returns A callable JavaScript function with metadata
+   */
+  createFunctionFromSchema(schema, serverName) {
+    const cacheKey = `${serverName}__${schema.name}`;
+    if (this.#functionCache.has(cacheKey)) {
+      return this.#functionCache.get(cacheKey);
+    }
+    try {
+      const generatedFunction = this.buildFunction(schema, serverName);
+      this.#functionCache.set(cacheKey, generatedFunction);
+      return generatedFunction;
+    } catch (error) {
+      throw new McpdError(
+        `Error creating function ${cacheKey}: ${error.message}`,
+        error
+      );
+    }
+  }
+  /**
+   * Build the actual function from the schema.
+   *
+   * @param schema - The tool schema
+   * @param serverName - The server name
+   * @returns The generated function with metadata
+   */
+  buildFunction(schema, serverName) {
+    const inputSchema = schema.inputSchema || {};
+    const properties = inputSchema.properties || {};
+    const required = new Set(inputSchema.required || []);
+    const implementation = async (...args) => {
+      let params = {};
+      if (args.length === 1 && typeof args[0] === "object" && args[0] !== null && !Array.isArray(args[0])) {
+        params = args[0];
+      } else {
+        const propertyNames = Object.keys(properties);
+        for (let i = 0; i < args.length && i < propertyNames.length; i++) {
+          const propertyName = propertyNames[i];
+          if (propertyName) {
+            params[propertyName] = args[i];
+          }
+        }
+      }
+      const missingParams = [];
+      for (const paramName of required) {
+        if (!(paramName in params) || params[paramName] === null || params[paramName] === void 0) {
+          missingParams.push(paramName);
+        }
+      }
+      if (missingParams.length > 0) {
+        throw new ValidationError(
+          `Missing required parameters: ${missingParams.join(", ")}`,
+          missingParams
+        );
+      }
+      const validationErrors = [];
+      for (const [paramName, paramValue] of Object.entries(params)) {
+        const paramSchema = properties[paramName];
+        if (paramValue !== null && paramValue !== void 0 && paramSchema) {
+          if (!TypeConverter.validateValue(paramValue, paramSchema)) {
+            const expectedType = TypeConverter.getTypeDescription(paramSchema);
+            validationErrors.push(
+              `Parameter '${paramName}' should be ${expectedType}, got ${typeof paramValue}`
+            );
+          }
+        }
+      }
+      if (validationErrors.length > 0) {
+        throw new ValidationError(
+          `Parameter validation failed: ${validationErrors.join("; ")}`,
+          validationErrors
+        );
+      }
+      const cleanParams = {};
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== null && value !== void 0) {
+          cleanParams[key] = value;
+        }
+      }
+      return this.#performCall(serverName, schema.name, cleanParams);
+    };
+    const invoke = async (args) => {
+      return implementation(args);
+    };
+    const execute = async (args) => {
+      return implementation(args);
+    };
+    const zodSchema = this.#jsonSchemaToZod(inputSchema);
+    const qualifiedName = this.functionName(serverName, schema.name);
+    const docstring = this.createDocstring(schema);
+    const agentFunction = implementation;
+    Object.defineProperty(agentFunction, "name", {
+      value: qualifiedName,
+      writable: false,
+      enumerable: true,
+      configurable: true
+    });
+    agentFunction.description = schema.description || docstring.split("\n")[0] || "No description provided";
+    agentFunction.schema = zodSchema;
+    agentFunction.invoke = invoke;
+    agentFunction.lc_namespace = ["mcpd", "tools"];
+    agentFunction.returnDirect = false;
+    agentFunction.inputSchema = zodSchema;
+    agentFunction.execute = execute;
+    agentFunction._schema = schema;
+    agentFunction._serverName = serverName;
+    agentFunction._toolName = schema.name;
+    return agentFunction;
+  }
+  /**
+   * Generate a comprehensive docstring for the dynamically created function.
+   *
+   * This method builds a properly formatted docstring that includes the
+   * tool's description, parameter documentation with optional/required status,
+   * return value information, and exception documentation.
+   *
+   * @param schema - The MCP tool's JSON Schema definition
+   * @returns A multi-line string containing the complete docstring text
+   */
+  createDocstring(schema) {
+    const description = schema.description || "No description provided";
+    const inputSchema = schema.inputSchema || {};
+    const properties = inputSchema.properties || {};
+    const required = new Set(inputSchema.required || []);
+    const docstringParts = [description];
+    if (Object.keys(properties).length > 0) {
+      docstringParts.push("");
+      docstringParts.push("Parameters:");
+      for (const [paramName, paramInfo] of Object.entries(properties)) {
+        const isRequired = required.has(paramName);
+        const paramDesc = paramInfo.description || "No description provided";
+        const paramType = TypeConverter.getTypeDescription(paramInfo);
+        const requiredText = isRequired ? "" : " (optional)";
+        docstringParts.push(
+          `  ${paramName} (${paramType}): ${paramDesc}${requiredText}`
+        );
+      }
+    }
+    docstringParts.push("");
+    docstringParts.push("Returns:");
+    docstringParts.push("  Promise<any>: Function execution result");
+    docstringParts.push("");
+    docstringParts.push("Throws:");
+    docstringParts.push(
+      "  ValidationError: If required parameters are missing or invalid"
+    );
+    docstringParts.push("  McpdError: If the API call fails");
+    return docstringParts.join("\n");
+  }
+  /**
+   * Clear the function cache.
+   *
+   * This method clears all cached generated functions, forcing them to be
+   * regenerated on the next call to createFunctionFromSchema().
+   */
+  clearCache() {
+    this.#functionCache.clear();
+  }
+  /**
+   * Get the current cache size.
+   *
+   * @returns The number of functions currently cached
+   */
+  getCacheSize() {
+    return this.#functionCache.size;
+  }
+}
+const API_BASE = "/api/v1";
+const SERVERS_BASE = `${API_BASE}/servers`;
+const HEALTH_SERVERS_BASE = `${API_BASE}/health/servers`;
+const API_PATHS = {
+  // Server management
+  SERVERS: SERVERS_BASE,
+  // Tools
+  SERVER_TOOLS: (serverName) => `${SERVERS_BASE}/${encodeURIComponent(serverName)}/tools`,
+  TOOL_CALL: (serverName, toolName) => `${SERVERS_BASE}/${encodeURIComponent(serverName)}/tools/${encodeURIComponent(toolName)}`,
+  // Health
+  HEALTH_ALL: HEALTH_SERVERS_BASE,
+  HEALTH_SERVER: (serverName) => `${HEALTH_SERVERS_BASE}/${encodeURIComponent(serverName)}`
+};
+class McpdClient {
+  #endpoint;
+  #apiKey;
+  #timeout;
+  #serverHealthCache;
+  #functionBuilder;
+  #cacheableExceptions = /* @__PURE__ */ new Set([
+    ServerNotFoundError,
+    ServerUnhealthyError,
+    AuthenticationError
+  ]);
+  /**
+   * Namespace for accessing MCP servers and their tools.
+   */
+  servers;
+  /**
+   * Initialize a new McpdClient instance.
+   *
+   * @param options - Configuration options for the client
+   */
+  constructor(options) {
+    this.#endpoint = options.apiEndpoint.replace(/\/$/, "");
+    this.#apiKey = options.apiKey;
+    this.#timeout = options.timeout ?? 3e4;
+    const healthCacheTtlMs = (options.healthCacheTtl ?? 10) * 1e3;
+    this.#serverHealthCache = createCache({
+      max: 100,
+      // TODO: Extract to const like Python SDK see:
+      //  _SERVER_HEALTH_CACHE_MAXSIZE: int = 100
+      // """Maximum number of server health entries to cache.
+      // Prevents unbounded memory growth while allowing legitimate large-scale monitoring."""
+      ttl: healthCacheTtlMs
+    });
+    this.servers = new ServersNamespace(
+      this.#performCall.bind(this),
+      this.#getToolsByServer.bind(this)
+    );
+    this.#functionBuilder = new FunctionBuilder(this.#performCall.bind(this));
+  }
+  /**
+   * Make an HTTP request to the mcpd daemon.
+   *
+   * @param path - The API path (e.g., '/servers', '/servers/{server_name}/tools')
+   * @param options - Request options
+   * @returns The JSON response from the daemon
+   * @throws {McpdError} If the request fails
+   */
+  async #request(path, options = {}) {
+    const url = `${this.#endpoint}${path}`;
+    const headers = {
+      "Content-Type": "application/json",
+      ...options.headers || {}
+    };
+    if (this.#apiKey) {
+      headers["Authorization"] = `Bearer ${this.#apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.#timeout);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const body = await response.text();
+        let errorModel = null;
+        try {
+          errorModel = JSON.parse(body);
+        } catch {
+        }
+        if (errorModel && errorModel.detail) {
+          const errorDetails = errorModel.errors?.map((e) => `${e.location}: ${e.message}`).join("; ");
+          const fullMessage = errorDetails ? `${errorModel.detail} - ${errorDetails}` : errorModel.detail;
+          if (response.status === 401 || response.status === 403) {
+            throw new AuthenticationError(fullMessage);
+          }
+          throw new McpdError(
+            `${errorModel.title || "Request failed"}: ${fullMessage}`
+          );
+        }
+        if (response.status === 401 || response.status === 403) {
+          throw new AuthenticationError(
+            `Authentication failed: ${response.status} ${response.statusText}`
+          );
+        }
+        throw new McpdError(
+          `Request failed: ${response.status} ${response.statusText} - ${body}`
+        );
+      }
+      try {
+        return await response.json();
+      } catch (error) {
+        throw new McpdError("Failed to parse JSON response", error);
+      }
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        throw new TimeoutError(
+          `Request timed out after ${this.#timeout}ms`,
+          path,
+          this.#timeout
+        );
+      }
+      if (error instanceof TypeError && error.message.includes("fetch")) {
+        throw new ConnectionError(
+          `Cannot connect to mcpd daemon at ${this.#endpoint}. Is it running?`,
+          error
+        );
+      }
+      if (error instanceof McpdError) {
+        throw error;
+      }
+      throw new McpdError(
+        `Request failed: ${error.message}`,
+        error
+      );
+    }
+  }
+  /**
+   * Get a list of all configured MCP servers.
+   *
+   * @returns Array of server names
+   * @throws {McpdError} If the request fails
+   *
+   * @example
+   * ```typescript
+   * const servers = await client.listServers();
+   * console.log(servers); // ['time', 'fetch', 'git']
+   * ```
+   */
+  async listServers() {
+    return await this.#request(API_PATHS.SERVERS);
+  }
+  /**
+   * Get tool schemas from all (or specific) MCP servers with transformed names.
+   *
+   * IMPORTANT: Tool names are transformed to `serverName__toolName` format to:
+   * 1. Prevent naming clashes when aggregating tools from multiple servers
+   * 2. Identify which server each tool belongs to
+   *
+   * 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.
+   *
+   * Tool fetches from multiple servers are executed concurrently for optimal performance.
+   *
+   * This is useful for:
+   * - MCP servers that aggregate and re-expose tools from multiple upstream servers
+   * - Tool inspection and discovery across all servers
+   * - Custom tooling that needs raw MCP tool schemas
+   *
+   * @param options - Optional configuration
+   * @param options.servers - Array of server names to include. If not specified, includes all servers.
+   * @returns Array of tool schemas with transformed names (serverName__toolName). Only includes tools from healthy servers.
+   * @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 health check or initial server listing fails
+   *
+   * @example
+   * ```typescript
+   * // Get all tools from all servers
+   * const allTools = await client.getToolSchemas();
+   * // Returns: [
+   * //   { name: "time__get_current_time", description: "...", ... },
+   * //   { name: "fetch__fetch_url", description: "...", ... }
+   * // ]
+   *
+   * // Get tools from specific servers only
+   * const someTools = await client.getToolSchemas({ servers: ['time', 'fetch'] });
+   *
+   * // Original tool name "get_current_time" becomes "time__get_current_time"
+   * // This prevents clashes if multiple servers have tools with the same name
+   * ```
+   */
+  async getToolSchemas(options) {
+    const { servers } = options || {};
+    const serverNames = servers && servers.length > 0 ? servers : await this.listServers();
+    const healthMap = await this.getServerHealth();
+    const healthyServers = serverNames.filter((name) => {
+      const health = healthMap[name];
+      return health && HealthStatusHelpers.isHealthy(health.status);
+    });
+    const results = await Promise.allSettled(
+      healthyServers.map(async (serverName) => ({
+        serverName,
+        tools: await this.#getToolsByServer(serverName)
+      }))
+    );
+    const allTools = [];
+    for (const result of results) {
+      if (result.status === "fulfilled") {
+        const { serverName, tools } = result.value;
+        for (const tool of tools) {
+          allTools.push({
+            ...tool,
+            name: `${serverName}__${tool.name}`
+          });
+        }
+      } else {
+        console.warn(`Failed to get tools for server:`, result.reason);
+      }
+    }
+    return allTools;
+  }
+  /**
+   * Internal method to get tool schemas for a server.
+   * 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 {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) {
+    await this.#ensureServerHealthy(serverName);
+    const path = API_PATHS.SERVER_TOOLS(serverName);
+    const response = await this.#request(path);
+    if (!response.tools) {
+      throw new ServerNotFoundError(
+        `Server '${serverName}' not found`,
+        serverName
+      );
+    }
+    return response.tools;
+  }
+  async getServerHealth(serverName) {
+    if (serverName) {
+      const cacheKey = `health:${serverName}`;
+      const cached = this.#serverHealthCache.get(cacheKey);
+      if (cached !== void 0) {
+        if (cached instanceof Error) {
+          throw cached;
+        }
+        return cached;
+      }
+      try {
+        const path = API_PATHS.HEALTH_SERVER(serverName);
+        const health = await this.#request(path);
+        this.#serverHealthCache.set(cacheKey, health);
+        return health;
+      } catch (error) {
+        if (error instanceof Error) {
+          for (const errorType of this.#cacheableExceptions) {
+            if (error instanceof errorType) {
+              this.#serverHealthCache.set(cacheKey, error);
+              break;
+            }
+          }
+        }
+        throw error;
+      }
+    } else {
+      const response = await this.#request(
+        API_PATHS.HEALTH_ALL
+      );
+      const healthMap = {};
+      for (const server of response.servers) {
+        healthMap[server.name] = server;
+        const cacheKey = `health:${server.name}`;
+        this.#serverHealthCache.set(cacheKey, server);
+      }
+      return healthMap;
+    }
+  }
+  /**
+   * 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
+   *
+   * @example
+   * ```typescript
+   * if (await client.isServerHealthy('time')) {
+   *   const time = await client.servers.time.get_current_time();
+   * }
+   * ```
+   */
+  async isServerHealthy(serverName) {
+    try {
+      const health = await this.getServerHealth(serverName);
+      return HealthStatusHelpers.isHealthy(health.status);
+    } catch (error) {
+      if (error instanceof ServerNotFoundError) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  /**
+   * 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
+   */
+  async #ensureServerHealthy(serverName) {
+    const health = await this.getServerHealth(serverName);
+    if (!health) {
+      throw new ServerNotFoundError(
+        `Server '${serverName}' not found`,
+        serverName
+      );
+    }
+    if (!HealthStatusHelpers.isHealthy(health.status)) {
+      throw new ServerUnhealthyError(
+        `Server '${serverName}' is not healthy: ${health.status}`,
+        serverName,
+        health.status
+      );
+    }
+  }
+  /**
+   * Internal method to perform a tool call on a server.
+   *
+   * ⚠️ This method is truly private and cannot be accessed by SDK consumers.
+   * Use the fluent API instead: `client.servers.foo.tools.bar(args)`
+   *
+   * This method is used internally by:
+   * - ToolsProxy (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
+   * @internal
+   */
+  async #performCall(serverName, toolName, args) {
+    const path = API_PATHS.TOOL_CALL(serverName, toolName);
+    try {
+      const response = await this.#request(path, {
+        method: "POST",
+        body: JSON.stringify(args || {})
+      });
+      if (typeof response === "string") {
+        try {
+          return JSON.parse(response);
+        } catch {
+          return response;
+        }
+      }
+      return response;
+    } catch (error) {
+      if (error instanceof McpdError) {
+        throw error;
+      }
+      throw new ToolExecutionError(
+        `Failed to execute tool '${toolName}' on server '${serverName}': ${error.message}`,
+        serverName,
+        toolName,
+        void 0,
+        error
+      );
+    }
+  }
+  /**
+   * Clear the cached agent tools functions.
+   * This should be called when the tool schemas might have changed.
+   */
+  clearAgentToolsCache() {
+    this.#functionBuilder.clearCache();
+  }
+  /**
+   * Clear the server health cache.
+   * This forces fresh health checks on the next getServerHealth() or isServerHealthy() call.
+   */
+  clearServerHealthCache() {
+    this.#serverHealthCache.clear();
+  }
+  /**
+   * Generate callable functions for use with AI agent frameworks (internal).
+   *
+   * This method queries 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.
+   *
+   * Tool fetches from multiple servers are executed concurrently for optimal performance.
+   *
+   * @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.
+   *
+   * @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
+   * @internal
+   */
+  async agentTools(servers) {
+    const serverNames = servers && servers.length > 0 ? servers : await this.listServers();
+    const healthMap = await this.getServerHealth();
+    const healthyServers = serverNames.filter((name) => {
+      const health = healthMap[name];
+      return health && HealthStatusHelpers.isHealthy(health.status);
+    });
+    const results = await Promise.allSettled(
+      healthyServers.map(async (serverName) => ({
+        serverName,
+        tools: await this.#getToolsByServer(serverName)
+      }))
+    );
+    const agentTools = [];
+    for (const result of results) {
+      if (result.status === "fulfilled") {
+        const { serverName, tools } = result.value;
+        for (const toolSchema of tools) {
+          const func = this.#functionBuilder.createFunctionFromSchema(
+            toolSchema,
+            serverName
+          );
+          agentTools.push(func);
+        }
+      } else {
+        console.warn(`Failed to get tools for server:`, result.reason);
+      }
+    }
+    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;
+    }
+  }
+}
+export {
+  AuthenticationError,
+  ConnectionError,
+  HealthStatus,
+  HealthStatusHelpers,
+  McpdClient,
+  McpdError,
+  ServerNotFoundError,
+  ServerUnhealthyError,
+  TimeoutError,
+  ToolExecutionError,
+  ToolNotFoundError,
+  ValidationError
+};
+//# sourceMappingURL=index.mjs.map