Add logging

 *Add logging
* Update README
* Add mock 'fetch' factory for the API
* Tweak example log messages

Author: peteski22

README.md

@@ -112,6 +112,110 @@ const client = new McpdClient({
 });
 ```
 
+### Logging
+
+The SDK includes optional logging for warnings about unhealthy or non-existent servers that are skipped during operations.
+
+**Important:** Logging is disabled by default. Only enable logging in non-MCP-server contexts. MCP servers using stdio transport for JSON-RPC communication should never enable logging, as it will contaminate stdout/stderr and break the protocol.
+
+#### Using Environment Variable
+
+Set the `MCPD_LOG_LEVEL` environment variable to control logging:
+
+```bash
+# Valid levels: trace, debug, info, warn, error, off (default)
+export MCPD_LOG_LEVEL=warn
+```
+
+**Available Log Levels:**
+
+| Level   | Description                                                     |
+| ------- | --------------------------------------------------------------- |
+| `trace` | Verbose information (includes `debug`, `info`, `warn`, `error`) |
+| `debug` | Debug information (includes `info`, `warn`, `error`)            |
+| `info`  | General informational messages (includes `warn`, `error`)       |
+| `warn`  | Warning messages only (includes `error`)                        |
+| `error` | Error messages only                                             |
+| `off`   | (...or unset) Logging disabled (default)                        |
+
+```typescript
+// Logging is automatically enabled based on MCPD_LOG_LEVEL
+const client = new McpdClient({
+  apiEndpoint: "http://localhost:8090",
+});
+```
+
+#### Using Custom Logger
+
+For advanced use cases, inject your own logger implementation.
+
+**Partial Logger Support:** You can provide only the methods you want to customize. Any omitted methods will fall back to the default logger, which respects `MCPD_LOG_LEVEL`.
+
+```typescript
+import { McpdClient } from "@mozilla-ai/mcpd";
+
+// Full custom logger
+const client = new McpdClient({
+  apiEndpoint: "http://localhost:8090",
+  logger: {
+    trace: (...args) => myLogger.trace(args),
+    debug: (...args) => myLogger.debug(args),
+    info: (...args) => myLogger.info(args),
+    warn: (...args) => myLogger.warn(args),
+    error: (...args) => myLogger.error(args),
+  },
+});
+
+// Partial logger: custom warn/error, default (MCPD_LOG_LEVEL-aware) for others
+const client2 = new McpdClient({
+  apiEndpoint: "http://localhost:8090",
+  logger: {
+    warn: (msg) => console.warn(`[mcpd] ${msg}`),
+    error: (msg) => console.error(`[mcpd] ${msg}`),
+    // trace, debug, info use default logger (respects MCPD_LOG_LEVEL)
+  },
+});
+```
+
+#### Disabling Logging
+
+To disable logging, simply ensure `MCPD_LOG_LEVEL` is unset or set to `off` (the default):
+
+```typescript
+// Logging is disabled by default (no configuration needed)
+const client = new McpdClient({
+  apiEndpoint: "http://localhost:8090",
+});
+```
+
+If you need to disable logging even when `MCPD_LOG_LEVEL` is set (rare case), provide a custom logger with no-op implementations:
+
+```typescript
+// Override MCPD_LOG_LEVEL to force disable
+const client = new McpdClient({
+  apiEndpoint: "http://localhost:8090",
+  logger: {
+    trace: () => {},
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  },
+});
+```
+
+When logging is enabled, warnings are emitted for:
+
+- Unhealthy servers that are skipped (e.g., status `timeout`, `unreachable`)
+- Non-existent servers specified in filter options
+
+Example warning messages:
+
+```text
+Skipping unhealthy server 'time' with status 'timeout'
+Skipping non-existent server 'unknown'
+```
+
 ### Core Methods
 
 #### `client.listServers()`

examples/langchain/index.js

@@ -106,7 +106,7 @@ async function main() {
   } catch (error) {
     if (error instanceof McpdError) {
       console.error('------------------------------');
-      console.error(`[MCPD ERROR] ${error.message}`);
+      console.error(`[mcpd ERROR] ${error.message}`);
       console.error('------------------------------');
     } else if (error.code === 'ECONNREFUSED') {
       console.error('------------------------------');

examples/vercel-ai/index.js

@@ -97,7 +97,7 @@ async function main() {
   } catch (error) {
     if (error instanceof McpdError) {
       console.error('------------------------------');
-      console.error(`[MCPD ERROR] ${error.message}`);
+      console.error(`[mcpd ERROR] ${error.message}`);
       console.error('------------------------------');
     } else if (error.code === 'ECONNREFUSED') {
       console.error('------------------------------');

src/client.ts

@@ -43,6 +43,7 @@ import { createCache } from "./utils/cache";
 import { ServersNamespace } from "./dynamicCaller";
 import { FunctionBuilder, type AgentFunction } from "./functionBuilder";
 import { API_PATHS } from "./apiPaths";
+import { createLogger, type Logger } from "./logger";
 
 /**
  * Maximum number of server health entries to cache.
@@ -94,6 +95,7 @@ export class McpdClient {
   readonly #timeout: number;
   readonly #serverHealthCache: LRUCache<string, ServerHealth | Error>;
   readonly #functionBuilder: FunctionBuilder;
+  readonly #logger: Logger;
   readonly #cacheableExceptions = new Set([
     ServerNotFoundError,
     ServerUnhealthyError,
@@ -111,19 +113,22 @@ export class McpdClient {
    * @param options - Configuration options for the client
    */
   constructor(options: McpdClientOptions) {
-    // Remove trailing slash from endpoint
+    // Remove trailing slash from endpoint.
     this.#endpoint = options.apiEndpoint.replace(/\/$/, "");
     this.#apiKey = options.apiKey;
     this.#timeout = options.timeout ?? 30000;
 
-    // Setup health cache
-    const healthCacheTtlMs = (options.healthCacheTtl ?? 10) * 1000; // Convert to milliseconds
+    // Setup health cache.
+    const healthCacheTtlMs = (options.healthCacheTtl ?? 10) * 1000; // Convert to milliseconds.
     this.#serverHealthCache = createCache({
       max: SERVER_HEALTH_CACHE_MAXSIZE,
       ttl: healthCacheTtlMs,
     });
 
-    // Initialize servers namespace and function builder with injected functions
+    // Setup logger (the default logger uses MCPD_LOG_LEVEL).
+    this.#logger = createLogger(options.logger);
+
+    // Initialize servers namespace and function builder with injected functions.
     this.servers = new ServersNamespace({
       performCall: this.#performCall.bind(this),
       getTools: this.#getToolsByServer.bind(this),
@@ -608,20 +613,33 @@ export class McpdClient {
    * 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.
    *
-   * @param servers - Optional array of server names. If not provided, fetches all servers.
-   * @returns Array of healthy server names
-   * @internal
+   * If logging is enabled, warnings are logged for servers that are skipped
+   * due to unhealthy status or non-existence.
+   *
+   * @param servers - Optional list of server names to filter. If not provided,
+   *                  checks health of all servers.
+   * @returns List of server names with 'ok' health status.
    */
   async #getHealthyServers(servers?: string[]): Promise<string[]> {
-    // Get server names if not provided.
-    const serverNames =
-      servers && servers.length > 0 ? servers : await this.listServers();
-
-    // Get health status and filter to healthy servers.
+    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;
     });
   }
 
@@ -704,9 +722,9 @@ export class McpdClient {
    * 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.
+   * This method automatically filters out unhealthy servers by checking their health status before fetching tools.
+   * Unhealthy servers are skipped (with optional warnings when logging is enabled) to ensure the
+   * method returns quickly without waiting for timeouts on failed servers.
    *
    * Tool fetches from multiple servers are executed concurrently for optimal performance.
    *
@@ -755,9 +773,9 @@ export class McpdClient {
    * 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.
+   * This method automatically filters out unhealthy servers by checking their health status before fetching tools.
+   * Unhealthy servers are skipped (with optional warnings when logging is enabled) to ensure the
+   * method returns quickly without waiting for timeouts on failed servers.
    *
    * Tool fetches from multiple servers are executed concurrently for optimal performance.
    *

src/logger.ts

@@ -0,0 +1,149 @@
+/**
+ * Internal logging infrastructure for the mcpd SDK.
+ *
+ * This module provides a logging shim controlled by the MCPD_LOG_LEVEL environment
+ * variable.
+ *
+ * Logging is disabled by default.
+ *
+ * NOTE: It is recommended that you only enable MCPD_LOG_LEVEL in non-MCP-server contexts.
+ * MCP servers using stdio transport for JSON-RPC communication should avoid enabling logging
+ * to avoid contaminating stdout/stderr.
+ */
+
+/**
+ * Valid log levels for MCPD_LOG_LEVEL environment variable.
+ */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "off";
+
+/**
+ * Logger interface defining the SDK's logging contract.
+ *
+ * Each method accepts a message and optional arguments for string formatting.
+ * A full Logger implementation provides all methods.
+ */
+export interface Logger {
+  /**
+   * Log a trace-level message (most verbose).
+   *
+   * @param args - Message and optional formatting arguments.
+   */
+  trace(...args: unknown[]): void;
+
+  /**
+   * Log a debug-level message.
+   *
+   * @param args - Message and optional formatting arguments.
+   */
+  debug(...args: unknown[]): void;
+
+  /**
+   * Log an info-level message.
+   *
+   * @param args - Message and optional formatting arguments.
+   */
+  info(...args: unknown[]): void;
+
+  /**
+   * Log a warning-level message.
+   *
+   * @param args - Message and optional formatting arguments.
+   */
+  warn(...args: unknown[]): void;
+
+  /**
+   * Log an error-level message.
+   *
+   * @param args - Message and optional formatting arguments.
+   */
+  error(...args: unknown[]): void;
+}
+
+// Numeric ranks for log levels (lower = more verbose).
+const ranks: Record<LogLevel, number> = {
+  trace: 5,
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  off: 1000,
+};
+
+// Attempts to resolve log level from a (case insensitive) environment variable value.
+// Defaults to "off" if unrecognized.
+function resolve(raw: string | undefined): LogLevel {
+  const candidate = raw?.toLowerCase() as LogLevel | undefined;
+  return candidate && candidate in ranks ? candidate : "off";
+}
+
+// Lazily resolve the level at call time to support testing.
+function getLevel(): LogLevel {
+  return resolve(
+    typeof process !== "undefined" ? process.env.MCPD_LOG_LEVEL : undefined,
+  );
+}
+
+// Default logger implementation using console methods.
+function defaultLogger(): Logger {
+  const OFF: LogLevel = "off";
+
+  return {
+    trace: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== OFF && ranks[lvl] <= ranks.trace) console.trace(...args);
+    },
+    debug: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== OFF && ranks[lvl] <= ranks.debug) console.debug(...args);
+    },
+    info: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== OFF && ranks[lvl] <= ranks.info) console.info(...args);
+    },
+    warn: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== OFF && ranks[lvl] <= ranks.warn) console.warn(...args);
+    },
+    error: (...args) => {
+      const lvl = getLevel();
+      if (lvl !== OFF && ranks[lvl] <= ranks.error) console.error(...args);
+    },
+  };
+}
+
+/**
+ * Create a logger, optionally using a custom implementation.
+ *
+ * This function allows SDK users to inject their own logger implementation.
+ * Supports partial implementations - any omitted methods will fall back to the
+ * default logger, which respects the MCPD_LOG_LEVEL environment variable.
+ *
+ * @param impl - Optional custom Logger implementation or partial implementation.
+ *               If not provided, uses default logger controlled by MCPD_LOG_LEVEL.
+ *               If partially provided, custom methods are used and omitted methods
+ *               fall back to default logger (which respects MCPD_LOG_LEVEL).
+ * @returns A Logger instance with all methods implemented.
+ *
+ * @example
+ * ```typescript
+ * // Use default logger (controlled by MCPD_LOG_LEVEL).
+ * const logger = createLogger();
+ *
+ * // Partial logger: custom warn/error, default (MCPD_LOG_LEVEL-aware) for others.
+ * const logger = createLogger({
+ *   warn: (msg) => myCustomLogger.warning(msg),
+ *   error: (msg) => myCustomLogger.error(msg),
+ *   // trace, debug, info fall back to default logger (respects MCPD_LOG_LEVEL)
+ * });
+ * ```
+ */
+export function createLogger(impl?: Partial<Logger>): Logger {
+  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,
+  };
+}