@meldocio/mcp-stdio-proxy 1.0.22 → 1.0.24

package/lib/http/error-handler.js

@@ -0,0 +1,195 @@
+/**
+ * HTTP Error Handler
+ *
+ * Handles workspace-required and authentication errors from backend.
+ * Consolidates error handling logic that was duplicated 3+ times in proxy.js
+ */
+
+const { JSON_RPC_ERROR_CODES, CUSTOM_ERROR_CODES } = require('../protocol/error-codes');
+const { sendError, writeResponse } = require('../protocol/json-rpc');
+const { LOG_LEVELS } = require('../core/constants');
+
+/**
+ * Get current log level
+ */
+function getLogLevel() {
+  const level = (process.env.LOG_LEVEL || 'ERROR').toUpperCase();
+  return LOG_LEVELS[level] !== undefined ? LOG_LEVELS[level] : LOG_LEVELS.ERROR;
+}
+
+const LOG_LEVEL = getLogLevel();
+
+/**
+ * Log message based on level
+ */
+function log(level, message) {
+  if (LOG_LEVEL >= level) {
+    const levelName = Object.keys(LOG_LEVELS)[level] || 'UNKNOWN';
+    process.stderr.write(`[${levelName}] ${message}\n`);
+  }
+}
+
+/**
+ * Check if error indicates workspace is required
+ * @param {Object} error - Error object from response
+ * @returns {boolean} True if workspace required
+ */
+function isWorkspaceRequiredError(error) {
+  if (!error) return false;
+
+  const errorCode = error.code;
+  const errorMessage = String(error.message || '');
+  const errorData = error.data || {};
+
+  // Check for explicit workspace required code
+  if (errorCode === 'WORKSPACE_REQUIRED' || errorData.code === 'WORKSPACE_REQUIRED') {
+    return true;
+  }
+
+  // Check for workspace message in error
+  const hasWorkspaceMessage =
+    errorMessage.includes('Multiple workspaces available') ||
+    errorMessage.includes('Specify workspace');
+
+  // Server error with workspace message
+  if (errorCode === JSON_RPC_ERROR_CODES.SERVER_ERROR && hasWorkspaceMessage) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if error indicates authentication is required
+ * @param {Object} error - Error object from response
+ * @returns {boolean} True if auth required
+ */
+function isAuthRequiredError(error) {
+  if (!error) return false;
+
+  const errorCode = error.code;
+  const errorData = error.data || {};
+
+  return errorCode === 'AUTH_REQUIRED' || errorData.code === 'AUTH_REQUIRED';
+}
+
+/**
+ * Handle workspace required error
+ * @param {string|number} requestId - Request ID
+ * @param {string} [toolName] - Tool name being called
+ */
+function handleWorkspaceRequiredError(requestId, toolName) {
+  log(LOG_LEVELS.DEBUG, `Detected WORKSPACE_REQUIRED error for tool: ${toolName || 'unknown'}`);
+
+  // Special handling for list_workspaces tool
+  if (toolName === 'list_workspaces') {
+    const message = `Backend requires workspace selection even for ${toolName}. Please set a default workspace using set_workspace tool first, or contact support if this persists.`;
+    sendError(requestId, JSON_RPC_ERROR_CODES.SERVER_ERROR, message, {
+      code: 'WORKSPACE_REQUIRED',
+      hint: 'Try setting a default workspace first using set_workspace tool, or specify workspaceAlias/workspaceId in the tool call arguments.'
+    });
+    return;
+  }
+
+  // General workspace required message
+  const message = 'Multiple workspaces available. Use list_workspaces tool to get list, then use set_workspace to set default workspace, or specify workspaceAlias or workspaceId parameter in tool call.';
+  sendError(requestId, JSON_RPC_ERROR_CODES.SERVER_ERROR, message, {
+    code: 'WORKSPACE_REQUIRED',
+    hint: 'Use list_workspaces tool to get available workspaces, then use set_workspace to set default, or specify workspaceAlias or workspaceId in tool call.'
+  });
+}
+
+/**
+ * Handle authentication required error
+ * @param {string|number} requestId - Request ID
+ */
+function handleAuthRequiredError(requestId) {
+  const message = 'Authentication required. Run: npx @meldocio/mcp-stdio-proxy@latest auth login';
+  sendError(requestId, CUSTOM_ERROR_CODES.AUTH_REQUIRED, message, {
+    code: 'AUTH_REQUIRED',
+    hint: 'Use auth_login_instructions tool to get login command'
+  });
+}
+
+/**
+ * Process backend response and handle special errors
+ * @param {Object} response - Axios response object
+ * @param {Object} request - Original request
+ * @returns {boolean} True if error was handled, false if should be forwarded
+ */
+function handleBackendResponse(response, request) {
+  const responseData = response.data || {};
+
+  // Successful HTTP response (200, 201, etc.)
+  if (response.status >= 200 && response.status < 300) {
+    // Ensure response has id
+    if (responseData && !responseData.id && request.id !== undefined) {
+      responseData.id = request.id;
+    }
+
+    // Check for error in response data
+    if (responseData.error) {
+      const error = responseData.error;
+      const toolName = request.params?.name;
+
+      log(LOG_LEVELS.DEBUG, `Error response: code=${error.code}, message="${error.message}", toolName=${toolName}`);
+
+      // Check for workspace required
+      if (isWorkspaceRequiredError(error)) {
+        handleWorkspaceRequiredError(request.id, toolName);
+        return true; // Handled
+      }
+
+      // Check for auth required
+      if (isAuthRequiredError(error)) {
+        handleAuthRequiredError(request.id);
+        return true; // Handled
+      }
+
+      // Forward unhandled errors as-is
+      log(LOG_LEVELS.DEBUG, `Forwarding unhandled error: ${JSON.stringify(error)}`);
+      writeResponse(responseData);
+      return true; // Handled (forwarded)
+    }
+
+    // Success response - forward as-is
+    writeResponse(responseData);
+    return true; // Handled
+  }
+
+  // HTTP error status (400, 401, 404, etc.)
+  log(LOG_LEVELS.DEBUG, `HTTP error status ${response.status}`);
+
+  const errorMessage = responseData.error?.message ||
+                      responseData.message ||
+                      `HTTP ${response.status}: ${response.statusText}`;
+
+  // Check for workspace/auth errors in HTTP error responses
+  const error = responseData.error || responseData;
+
+  if (isWorkspaceRequiredError(error)) {
+    const toolName = request.params?.name;
+    handleWorkspaceRequiredError(request.id, toolName);
+    return true;
+  }
+
+  if (isAuthRequiredError(error)) {
+    handleAuthRequiredError(request.id);
+    return true;
+  }
+
+  // Forward other HTTP errors
+  sendError(request.id, JSON_RPC_ERROR_CODES.SERVER_ERROR, errorMessage, {
+    httpStatus: response.status,
+    code: error.code || 'HTTP_ERROR'
+  });
+  return true;
+}
+
+module.exports = {
+  isWorkspaceRequiredError,
+  isAuthRequiredError,
+  handleWorkspaceRequiredError,
+  handleAuthRequiredError,
+  handleBackendResponse
+};

package/lib/install/config-manager.js

@@ -0,0 +1,203 @@
+/**
+ * Configuration File Manager
+ *
+ * Handles reading, writing, and validating MCP configuration files.
+ * Provides safe file operations with error handling.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Check if a file exists
+ * @param {string} filePath - Path to file
+ * @returns {boolean} True if file exists
+ */
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Read and parse JSON configuration file
+ * @param {string} filePath - Path to config file
+ * @returns {Object|null} Parsed configuration object, or null if file doesn't exist or parse fails
+ */
+function readConfig(filePath) {
+  try {
+    if (!fileExists(filePath)) {
+      return null;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch (error) {
+    // Return null on any error (file not found, parse error, etc.)
+    return null;
+  }
+}
+
+/**
+ * Write configuration object to JSON file
+ * Creates parent directories if they don't exist
+ * @param {string} filePath - Path to config file
+ * @param {Object} config - Configuration object to write
+ * @throws {Error} If write fails
+ */
+function writeConfig(filePath, config) {
+  const dir = path.dirname(filePath);
+
+  // Create directory if it doesn't exist
+  if (!fileExists(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Write config file with pretty formatting
+  const content = JSON.stringify(config, null, 2);
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+/**
+ * Safely read configuration with fallback to empty object
+ * @param {string} filePath - Path to config file
+ * @returns {Object} Configuration object (empty if file doesn't exist or is invalid)
+ */
+function readConfigSafe(filePath) {
+  const config = readConfig(filePath);
+  return config || {};
+}
+
+/**
+ * Backup configuration file before modification
+ * @param {string} filePath - Path to config file
+ * @returns {string|null} Path to backup file, or null if backup failed
+ */
+function backupConfig(filePath) {
+  try {
+    if (!fileExists(filePath)) {
+      return null;
+    }
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${filePath}.backup-${timestamp}`;
+
+    fs.copyFileSync(filePath, backupPath);
+    return backupPath;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Validate that config is a valid JSON object
+ * @param {any} config - Configuration to validate
+ * @returns {boolean} True if valid
+ */
+function isValidConfig(config) {
+  return config !== null && typeof config === 'object' && !Array.isArray(config);
+}
+
+/**
+ * Get file modification time
+ * @param {string} filePath - Path to file
+ * @returns {Date|null} Modification time, or null if file doesn't exist
+ */
+function getFileModTime(filePath) {
+  try {
+    if (!fileExists(filePath)) {
+      return null;
+    }
+    const stats = fs.statSync(filePath);
+    return stats.mtime;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Ensure parent directory exists for a file path
+ * @param {string} filePath - Path to file
+ */
+function ensureDirectoryExists(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fileExists(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Delete configuration file
+ * @param {string} filePath - Path to config file
+ * @returns {boolean} True if file was deleted, false if it didn't exist
+ */
+function deleteConfig(filePath) {
+  try {
+    if (!fileExists(filePath)) {
+      return false;
+    }
+    fs.unlinkSync(filePath);
+    return true;
+  } catch (error) {
+    throw new Error(`Failed to delete config file: ${error.message}`);
+  }
+}
+
+/**
+ * Read, modify, and write config in a single operation
+ * @param {string} filePath - Path to config file
+ * @param {Function} modifier - Function that takes config and returns modified config
+ * @param {boolean} [createBackup=false] - Whether to create backup before writing
+ * @returns {Object} { success: boolean, backupPath?: string, error?: string }
+ */
+function modifyConfig(filePath, modifier, createBackup = false) {
+  try {
+    // Read existing config
+    const config = readConfigSafe(filePath);
+
+    // Apply modifications
+    const modifiedConfig = modifier(config);
+
+    // Validate result
+    if (!isValidConfig(modifiedConfig)) {
+      return {
+        success: false,
+        error: 'Modified configuration is not a valid object'
+      };
+    }
+
+    // Create backup if requested
+    let backupPath = null;
+    if (createBackup && fileExists(filePath)) {
+      backupPath = backupConfig(filePath);
+    }
+
+    // Write modified config
+    writeConfig(filePath, modifiedConfig);
+
+    return {
+      success: true,
+      backupPath
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message
+    };
+  }
+}
+
+module.exports = {
+  fileExists,
+  readConfig,
+  writeConfig,
+  readConfigSafe,
+  backupConfig,
+  isValidConfig,
+  getFileModTime,
+  ensureDirectoryExists,
+  deleteConfig,
+  modifyConfig
+};

package/lib/install/config-paths.js

@@ -0,0 +1,198 @@
+/**
+ * Configuration Path Management
+ *
+ * Centralized configuration file path management for all MCP clients.
+ * Supports Claude Desktop, Cursor, Claude Code, and local installations.
+ */
+
+const os = require('os');
+const path = require('path');
+
+/**
+ * Platform detection utilities
+ */
+const PLATFORMS = {
+  MAC: 'darwin',
+  WINDOWS: 'win32',
+  LINUX: 'linux'
+};
+
+function getPlatform() {
+  return os.platform();
+}
+
+function isMac() {
+  return getPlatform() === PLATFORMS.MAC;
+}
+
+function isWindows() {
+  return getPlatform() === PLATFORMS.WINDOWS;
+}
+
+function isLinux() {
+  return getPlatform() === PLATFORMS.LINUX;
+}
+
+/**
+ * Get home directory
+ */
+function getHomeDir() {
+  return os.homedir();
+}
+
+/**
+ * Get current working directory
+ */
+function getCwd() {
+  return process.cwd();
+}
+
+/**
+ * Client configuration path resolvers
+ * Each function returns the appropriate config file path for the target client
+ */
+
+/**
+ * Get Claude Desktop config file path (platform-specific)
+ * @returns {string} Path to claude_desktop_config.json
+ */
+function getClaudeDesktopConfigPath() {
+  const homeDir = getHomeDir();
+
+  if (isMac()) {
+    return path.join(homeDir, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  }
+
+  if (isWindows()) {
+    const appData = process.env.APPDATA || path.join(homeDir, 'AppData', 'Roaming');
+    return path.join(appData, 'Claude', 'claude_desktop_config.json');
+  }
+
+  // Linux and others
+  return path.join(homeDir, '.config', 'Claude', 'claude_desktop_config.json');
+}
+
+/**
+ * Get Cursor project config file path (.cursor/mcp.json in current directory)
+ * @returns {string} Path to project-specific Cursor config
+ */
+function getCursorProjectConfigPath() {
+  return path.join(getCwd(), '.cursor', 'mcp.json');
+}
+
+/**
+ * Get Cursor global config file path (~/.cursor/mcp.json)
+ * @returns {string} Path to global Cursor config
+ */
+function getCursorGlobalConfigPath() {
+  return path.join(getHomeDir(), '.cursor', 'mcp.json');
+}
+
+/**
+ * Get Claude Code project config path (.mcp.json in current directory)
+ * @returns {string} Path to project-specific Claude Code config
+ */
+function getClaudeCodeProjectConfigPath() {
+  return path.join(getCwd(), '.mcp.json');
+}
+
+/**
+ * Get Claude Code user config path (~/.claude.json)
+ * @returns {string} Path to user-level Claude Code config
+ */
+function getClaudeCodeUserConfigPath() {
+  return path.join(getHomeDir(), '.claude.json');
+}
+
+/**
+ * Get Claude Code local config path (same as user, but with project context)
+ * Note: Local scope uses ~/.claude.json but stores project-specific paths
+ * @returns {string} Path to local Claude Code config
+ */
+function getClaudeCodeLocalConfigPath() {
+  return path.join(getHomeDir(), '.claude.json');
+}
+
+/**
+ * Get local mcp.json path (in current directory)
+ * @returns {string} Path to generic local MCP config
+ */
+function getLocalMcpJsonPath() {
+  return path.join(getCwd(), 'mcp.json');
+}
+
+/**
+ * Get config path by client type and scope
+ * @param {string} client - Client type: 'claude-desktop', 'cursor', 'claude-code', 'local'
+ * @param {string} [scope] - Installation scope: 'global', 'project', 'user', 'local'
+ * @returns {string} Config file path
+ * @throws {Error} If client type is unknown or scope is invalid
+ */
+function getConfigPath(client, scope = 'project') {
+  switch (client) {
+    case 'claude-desktop':
+      return getClaudeDesktopConfigPath();
+
+    case 'cursor':
+      if (scope === 'global') {
+        return getCursorGlobalConfigPath();
+      }
+      return getCursorProjectConfigPath();
+
+    case 'claude-code':
+      if (scope === 'user') {
+        return getClaudeCodeUserConfigPath();
+      }
+      if (scope === 'local') {
+        return getClaudeCodeLocalConfigPath();
+      }
+      return getClaudeCodeProjectConfigPath();
+
+    case 'local':
+      return getLocalMcpJsonPath();
+
+    default:
+      throw new Error(`Unknown client type: ${client}`);
+  }
+}
+
+/**
+ * Get friendly display name for client
+ * @param {string} client - Client type
+ * @returns {string} Display name
+ */
+function getClientDisplayName(client) {
+  const names = {
+    'claude-desktop': 'Claude Desktop',
+    'cursor': 'Cursor',
+    'claude-code': 'Claude Code',
+    'local': 'Local MCP'
+  };
+  return names[client] || client;
+}
+
+module.exports = {
+  // Platform utilities
+  getPlatform,
+  isMac,
+  isWindows,
+  isLinux,
+  getHomeDir,
+  getCwd,
+
+  // Individual path getters (for backward compatibility)
+  getClaudeDesktopConfigPath,
+  getCursorProjectConfigPath,
+  getCursorGlobalConfigPath,
+  getClaudeCodeProjectConfigPath,
+  getClaudeCodeUserConfigPath,
+  getClaudeCodeLocalConfigPath,
+  getLocalMcpJsonPath,
+
+  // Unified interface
+  getConfigPath,
+  getClientDisplayName,
+
+  // Constants
+  PLATFORMS
+};