@mctx-ai/mcp-server 0.3.0

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * @mctx-ai/mcp-server
+ *
+ * Build MCP servers with an Express-like API - no protocol knowledge required.
+ *
+ * Main package entry point that exports core functionality.
+ */
+
+// Core server factory
+export { createServer } from "./server.js";
+
+// Type system for tool/prompt inputs
+export { T, buildInputSchema } from "./types.js";
+
+// Advanced features
+export { conversation } from "./conversation.js";
+export { createProgress, PROGRESS_DEFAULTS } from "./progress.js";
+export { log } from "./log.js";

package/src/log.js

@@ -0,0 +1,213 @@
+/**
+ * Logging Module
+ *
+ * Provides structured logging with RFC 5424 severity levels.
+ * Logs are buffered and sent as MCP notifications by the server.
+ *
+ * @module log
+ */
+
+/**
+ * RFC 5424 severity levels (highest to lowest)
+ * Used for level comparison and filtering
+ */
+const LEVELS = {
+  emergency: 0, // System is unusable
+  alert: 1, // Action must be taken immediately
+  critical: 2, // Critical conditions
+  error: 3, // Error conditions
+  warning: 4, // Warning conditions
+  notice: 5, // Normal but significant condition
+  info: 6, // Informational messages
+  debug: 7, // Debug-level messages
+};
+
+/**
+ * Maximum log buffer size (FIFO eviction when exceeded)
+ * @private
+ */
+const MAX_LOG_BUFFER_SIZE = 10000;
+
+/**
+ * Log buffer - stores notifications until server flushes them
+ * @private
+ */
+let logBuffer = [];
+
+/**
+ * Current minimum log level (messages below this are filtered)
+ * @private
+ */
+let currentLogLevel = "debug"; // Default: log everything
+
+/**
+ * Creates a log notification object
+ * @private
+ * @param {string} level - Log level
+ * @param {*} data - Log data (any JSON-serializable value)
+ * @returns {Object} Log notification object
+ */
+function createLogNotification(level, data) {
+  // Check if we should log this level
+  if (!shouldLog(level, currentLogLevel)) {
+    return; // Don't add to buffer if below minimum level
+  }
+
+  const notification = {
+    type: "log",
+    level,
+    data,
+  };
+
+  logBuffer.push(notification);
+
+  // Enforce buffer size limit with FIFO eviction
+  if (logBuffer.length > MAX_LOG_BUFFER_SIZE) {
+    logBuffer.shift();
+  }
+
+  return notification;
+}
+
+/**
+ * Determines if a message should be logged based on severity levels
+ *
+ * @param {string} messageLevel - The level of the message being logged
+ * @param {string} clientLevel - The minimum level configured by client
+ * @returns {boolean} True if message should be logged
+ *
+ * @example
+ * shouldLog('error', 'warning')   // true (error >= warning)
+ * shouldLog('debug', 'info')      // false (debug < info)
+ * shouldLog('info', 'info')       // true (info >= info)
+ */
+export function shouldLog(messageLevel, clientLevel) {
+  const messageSeverity = LEVELS[messageLevel];
+  const clientSeverity = LEVELS[clientLevel];
+
+  // If either level is unknown, default to logging
+  if (messageSeverity === undefined || clientSeverity === undefined) {
+    return true;
+  }
+
+  // Lower numeric value = higher severity
+  // Message should be logged if its severity >= client's minimum severity
+  return messageSeverity <= clientSeverity;
+}
+
+/**
+ * Sets the minimum log level
+ * Messages below this level will be filtered out
+ *
+ * @param {string} level - Minimum log level (debug, info, notice, warning, error, critical, alert, emergency)
+ *
+ * @example
+ * setLogLevel('warning');  // Only log warning and above
+ * log.debug('test');       // Won't be logged
+ * log.error('problem');    // Will be logged
+ */
+export function setLogLevel(level) {
+  if (LEVELS[level] === undefined) {
+    throw new Error(
+      `Invalid log level: "${level}". Must be one of: ${Object.keys(LEVELS).join(", ")}`,
+    );
+  }
+  currentLogLevel = level;
+}
+
+/**
+ * Gets the current log buffer
+ * Server uses this to retrieve buffered notifications
+ *
+ * @returns {Array<Object>} Array of log notification objects
+ */
+export function getLogBuffer() {
+  return [...logBuffer]; // Return copy to prevent external modification
+}
+
+/**
+ * Clears the log buffer
+ * Server calls this after flushing notifications
+ */
+export function clearLogBuffer() {
+  logBuffer = [];
+}
+
+/**
+ * Log object with methods for each severity level
+ *
+ * Each method creates a log notification and adds it to the buffer.
+ * The server will flush these as MCP notifications.
+ *
+ * @example
+ * log.debug('Variable value:', { x: 42 });
+ * log.info('Server started on port 3000');
+ * log.warning('Rate limit approaching');
+ * log.error('Database connection failed', error);
+ * log.critical('System out of memory');
+ */
+export const log = {
+  /**
+   * Debug-level message (lowest severity)
+   * Used for detailed debugging information
+   */
+  debug(data) {
+    return createLogNotification("debug", data);
+  },
+
+  /**
+   * Informational message
+   * Used for general informational messages
+   */
+  info(data) {
+    return createLogNotification("info", data);
+  },
+
+  /**
+   * Notice - normal but significant condition
+   * Used for important events that are not errors
+   */
+  notice(data) {
+    return createLogNotification("notice", data);
+  },
+
+  /**
+   * Warning condition
+   * Used for warnings that don't prevent operation
+   */
+  warning(data) {
+    return createLogNotification("warning", data);
+  },
+
+  /**
+   * Error condition
+   * Used for errors that affect functionality
+   */
+  error(data) {
+    return createLogNotification("error", data);
+  },
+
+  /**
+   * Critical condition
+   * Used for critical conditions that require immediate attention
+   */
+  critical(data) {
+    return createLogNotification("critical", data);
+  },
+
+  /**
+   * Alert - action must be taken immediately
+   * Used for conditions requiring immediate operator intervention
+   */
+  alert(data) {
+    return createLogNotification("alert", data);
+  },
+
+  /**
+   * Emergency - system is unusable
+   * Used for system-wide failures
+   */
+  emergency(data) {
+    return createLogNotification("emergency", data);
+  },
+};

package/src/progress.js

@@ -0,0 +1,84 @@
+/**
+ * Progress Notifications Module
+ *
+ * Provides progress tracking for long-running generator tool handlers.
+ * Supports both determinate (with total) and indeterminate progress.
+ *
+ * @module progress
+ */
+
+/**
+ * Default configuration for generator guardrails
+ * Server will use these to prevent runaway generators
+ */
+export const PROGRESS_DEFAULTS = {
+  maxExecutionTime: 60000, // 60 seconds
+  maxYields: 10000,
+};
+
+/**
+ * Creates a progress step function for generator-based tools
+ *
+ * Returns a function that produces progress notification objects.
+ * Each call auto-increments the progress counter.
+ *
+ * @param {number} [total] - Total number of steps (optional, for determinate progress)
+ * @returns {Function} Step function that returns progress notification objects
+ *
+ * @example
+ * // Determinate progress (with known total)
+ * function* migrate({ sourceDb, targetDb }) {
+ *   const tables = await getTables(sourceDb);
+ *   const step = createProgress(tables.length);
+ *
+ *   for (const table of tables) {
+ *     yield step();  // { type: "progress", progress: 1, total: 5 }
+ *     await copyTable(table, sourceDb, targetDb);
+ *   }
+ *
+ *   return "Migration complete";
+ * }
+ *
+ * @example
+ * // Indeterminate progress (no total)
+ * function* processQueue({ queueUrl }) {
+ *   const step = createProgress();
+ *
+ *   while (hasMessages(queueUrl)) {
+ *     yield step();  // { type: "progress", progress: 1 }
+ *     await processMessage(queueUrl);
+ *   }
+ *
+ *   return "Queue processed";
+ * }
+ */
+export function createProgress(total) {
+  // Validate total if provided
+  if (total !== undefined && (typeof total !== "number" || total <= 0)) {
+    throw new Error(
+      "createProgress() total must be a positive number if provided",
+    );
+  }
+
+  let currentStep = 0;
+
+  /**
+   * Step function - call to generate next progress notification
+   * @returns {Object} Progress notification object
+   */
+  return function step() {
+    currentStep++;
+
+    const notification = {
+      type: "progress",
+      progress: currentStep,
+    };
+
+    // Include total only if provided (determinate progress)
+    if (total !== undefined) {
+      notification.total = total;
+    }
+
+    return notification;
+  };
+}

package/src/sampling.js

@@ -0,0 +1,130 @@
+/**
+ * Sampling Support Module
+ *
+ * Enables MCP servers to request LLM completions from clients.
+ * Provides the `ask` function for tools that need AI assistance.
+ *
+ * @module sampling
+ */
+
+/**
+ * Default timeout for sampling requests (30 seconds)
+ */
+const DEFAULT_TIMEOUT = 30000;
+
+/**
+ * Creates an ask function for a given request context
+ *
+ * The ask function allows tools to request LLM completions from the client.
+ * Returns null if the client doesn't support sampling.
+ *
+ * @param {Function} sendRequest - Callback to send MCP requests (async)
+ * @param {Object} clientCapabilities - Client capabilities from initialization
+ * @returns {Function|null} Ask function, or null if sampling not supported
+ *
+ * @example
+ * // In a tool handler
+ * function* summarize({ document, ask }) {
+ *   if (!ask) {
+ *     return "Client doesn't support sampling";
+ *   }
+ *
+ *   const summary = await ask("Summarize this document: " + document);
+ *   return summary;
+ * }
+ *
+ * @example
+ * // Advanced usage with options
+ * const result = await ask({
+ *   messages: [
+ *     { role: "user", content: { type: "text", text: "What is the capital of France?" } }
+ *   ],
+ *   modelPreferences: {
+ *     hints: [{ name: "claude-3-5-sonnet" }]
+ *   },
+ *   systemPrompt: "You are a helpful geography assistant",
+ *   maxTokens: 1000,
+ * });
+ */
+export function createAsk(sendRequest, clientCapabilities) {
+  // Validate inputs
+  if (typeof sendRequest !== "function") {
+    throw new Error("createAsk() requires sendRequest to be a function");
+  }
+
+  if (!clientCapabilities || typeof clientCapabilities !== "object") {
+    throw new Error("createAsk() requires clientCapabilities object");
+  }
+
+  // Check if client supports sampling
+  if (!clientCapabilities.sampling) {
+    return null;
+  }
+
+  /**
+   * Ask function - request LLM completion from client
+   *
+   * @param {string|Object} promptOrOptions - Simple prompt string, or options object
+   * @param {number} [timeout=30000] - Request timeout in milliseconds
+   * @returns {Promise<string>} The LLM response content
+   * @throws {Error} If request fails or times out
+   */
+  return async function ask(promptOrOptions, timeout = DEFAULT_TIMEOUT) {
+    let requestParams;
+
+    // Simple string prompt - wrap as messages array
+    if (typeof promptOrOptions === "string") {
+      requestParams = {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: promptOrOptions,
+            },
+          },
+        ],
+      };
+    } else if (promptOrOptions && typeof promptOrOptions === "object") {
+      // Advanced options object
+      requestParams = { ...promptOrOptions };
+
+      // Validate required fields
+      if (!requestParams.messages || !Array.isArray(requestParams.messages)) {
+        throw new Error("ask() options must include messages array");
+      }
+    } else {
+      throw new Error("ask() requires a string prompt or options object");
+    }
+
+    // Create timeout promise
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Sampling request timed out after ${timeout}ms`));
+      }, timeout);
+    });
+
+    // Send sampling request with timeout
+    try {
+      const responsePromise = sendRequest(
+        "sampling/createMessage",
+        requestParams,
+      );
+      const response = await Promise.race([responsePromise, timeoutPromise]);
+
+      // Extract content from response
+      if (!response || !response.content) {
+        throw new Error("Invalid sampling response: missing content");
+      }
+
+      return response.content;
+    } catch (error) {
+      // Re-throw with better context
+      if (error.message.includes("timed out")) {
+        throw error;
+      }
+
+      throw new Error(`Sampling request failed: ${error.message}`);
+    }
+  };
+}