@meldocio/mcp-stdio-proxy 1.0.22 → 1.0.24

package/lib/mcp/handlers.js

@@ -0,0 +1,185 @@
+/**
+ * MCP Protocol Method Handlers
+ *
+ * Handles MCP protocol methods (initialize, ping, tools/list, etc.)
+ * These are handled locally and not proxied to the backend.
+ */
+
+const { sendResponse, sendError } = require('../protocol/json-rpc');
+const { getToolsList } = require('../protocol/tools-schema');
+const { JSON_RPC_ERROR_CODES } = require('../protocol/error-codes');
+const { LOG_LEVELS, MCP_PROTOCOL_VERSION, SERVER_CAPABILITIES } = require('../core/constants');
+
+/**
+ * Get 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
+ */
+function log(level, message) {
+  if (LOG_LEVEL >= level) {
+    const levelName = Object.keys(LOG_LEVELS)[level] || 'UNKNOWN';
+    process.stderr.write(`[${levelName}] ${message}\n`);
+  }
+}
+
+/**
+ * Get package info
+ */
+function getPackageInfo() {
+  try {
+    const pkg = require('../../package.json');
+    return { name: pkg.name, version: pkg.version };
+  } catch (error) {
+    return { name: '@meldocio/mcp-stdio-proxy', version: '1.0.0' };
+  }
+}
+
+/**
+ * Handle MCP initialize method
+ * @param {Object} request - JSON-RPC request
+ */
+function handleInitialize(request) {
+  const pkg = getPackageInfo();
+
+  const result = {
+    protocolVersion: MCP_PROTOCOL_VERSION,
+    capabilities: {
+      tools: SERVER_CAPABILITIES.TOOLS ? {} : undefined,
+      resources: SERVER_CAPABILITIES.RESOURCES ? {} : undefined,
+      prompts: SERVER_CAPABILITIES.PROMPTS ? {} : undefined,
+      logging: SERVER_CAPABILITIES.LOGGING ? {} : undefined
+    },
+    serverInfo: {
+      name: pkg.name,
+      version: pkg.version
+    }
+  };
+
+  // Remove undefined capabilities
+  Object.keys(result.capabilities).forEach(key => {
+    if (result.capabilities[key] === undefined) {
+      delete result.capabilities[key];
+    }
+  });
+
+  log(LOG_LEVELS.DEBUG, 'Initialize request received');
+  sendResponse(request.id, result);
+}
+
+/**
+ * Handle MCP ping method (keep-alive)
+ * @param {Object} request - JSON-RPC request
+ */
+function handlePing(request) {
+  sendResponse(request.id, {});
+}
+
+/**
+ * Handle resources/list method
+ * Returns empty list as resources are not supported yet
+ * @param {Object} request - JSON-RPC request
+ */
+function handleResourcesList(request) {
+  sendResponse(request.id, {
+    resources: []
+  });
+}
+
+/**
+ * Handle tools/list method
+ * Always returns static list locally, never proxies to backend
+ * @param {Object} request - JSON-RPC request
+ */
+function handleToolsList(request) {
+  try {
+    const tools = getToolsList();
+
+    // Log tool names for debugging
+    const toolNames = tools.map(t => t.name).join(', ');
+    log(LOG_LEVELS.INFO, `Returning ${tools.length} tools locally: ${toolNames}`);
+
+    sendResponse(request.id, {
+      tools: tools
+    });
+  } catch (error) {
+    // This should never happen, but if it does, send error response
+    log(LOG_LEVELS.ERROR, `Unexpected error in handleToolsList: ${error.message || 'Unknown error'}`);
+    log(LOG_LEVELS.DEBUG, `Error stack: ${error.stack || 'No stack trace'}`);
+
+    sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR,
+              `Failed to get tools list: ${error.message || 'Unknown error'}`, {
+                code: 'INTERNAL_ERROR'
+              });
+  }
+}
+
+/**
+ * Check if a method should be handled locally
+ * @param {string} method - Method name
+ * @returns {boolean} True if should be handled locally
+ */
+function isLocalMethod(method) {
+  const localMethods = [
+    'initialize',
+    'initialized',
+    'notifications/initialized',
+    'notifications/cancelled',
+    'ping',
+    'resources/list',
+    'tools/list'
+  ];
+  return localMethods.includes(method);
+}
+
+/**
+ * Route request to appropriate local handler
+ * @param {Object} request - JSON-RPC request
+ * @returns {boolean} True if handled, false if should be proxied
+ */
+function handleLocalMethod(request) {
+  const method = request.method;
+
+  switch (method) {
+    case 'initialize':
+      handleInitialize(request);
+      return true;
+
+    case 'initialized':
+    case 'notifications/initialized':
+    case 'notifications/cancelled':
+      // Notifications - no response needed
+      return true;
+
+    case 'ping':
+      handlePing(request);
+      return true;
+
+    case 'resources/list':
+      handleResourcesList(request);
+      return true;
+
+    case 'tools/list':
+      handleToolsList(request);
+      return true;
+
+    default:
+      return false; // Not a local method
+  }
+}
+
+module.exports = {
+  handleInitialize,
+  handlePing,
+  handleResourcesList,
+  handleToolsList,
+  isLocalMethod,
+  handleLocalMethod
+};

package/lib/mcp/tools-call.js

@@ -0,0 +1,179 @@
+/**
+ * MCP tools/call Handler
+ *
+ * Handles tools/call requests - routes to local tools or backend.
+ * Local tools: set_workspace, get_workspace, auth_status, auth_login_instructions
+ */
+
+const { sendResponse, sendError } = require('../protocol/json-rpc');
+const { JSON_RPC_ERROR_CODES } = require('../protocol/error-codes');
+const { getAuthStatus } = require('../core/auth');
+const { setWorkspaceAlias, getWorkspaceAlias } = require('../core/config');
+const { LOG_LEVELS } = require('../core/constants');
+
+/**
+ * Get 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
+ */
+function log(level, message) {
+  if (LOG_LEVEL >= level) {
+    const levelName = Object.keys(LOG_LEVELS)[level] || 'UNKNOWN';
+    process.stderr.write(`[${levelName}] ${message}\n`);
+  }
+}
+
+/**
+ * Create MCP tool response with text content
+ * @param {string} text - Text content
+ * @returns {Object} MCP result object
+ */
+function createToolResponse(text) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: text
+      }
+    ]
+  };
+}
+
+/**
+ * Handle set_workspace tool
+ * @param {Object} request - JSON-RPC request
+ * @param {Object} arguments_ - Tool arguments
+ */
+function handleSetWorkspace(request, arguments_) {
+  const alias = arguments_.alias;
+  if (!alias || typeof alias !== 'string') {
+    sendError(request.id, JSON_RPC_ERROR_CODES.INVALID_PARAMS, 'alias parameter is required and must be a string');
+    return;
+  }
+
+  try {
+    setWorkspaceAlias(alias);
+    sendResponse(request.id, createToolResponse(`Workspace alias set to: ${alias}`));
+  } catch (error) {
+    sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, `Failed to set workspace alias: ${error.message}`);
+  }
+}
+
+/**
+ * Handle get_workspace tool
+ * @param {Object} request - JSON-RPC request
+ */
+function handleGetWorkspace(request) {
+  try {
+    const workspaceAlias = getWorkspaceAlias();
+    const result = {
+      workspaceAlias: workspaceAlias || null,
+      source: workspaceAlias ? 'config' : 'not_found',
+      message: workspaceAlias ? `Current workspace: ${workspaceAlias}` : 'No workspace set in config'
+    };
+    sendResponse(request.id, createToolResponse(JSON.stringify(result, null, 2)));
+  } catch (error) {
+    sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, `Failed to get workspace: ${error.message}`);
+  }
+}
+
+/**
+ * Handle auth_status tool
+ * @param {Object} request - JSON-RPC request
+ */
+async function handleAuthStatus(request) {
+  try {
+    const authStatus = await getAuthStatus();
+    if (!authStatus) {
+      const result = {
+        authenticated: false,
+        message: 'Not authenticated. Run: npx @meldocio/mcp-stdio-proxy@latest auth login'
+      };
+      sendResponse(request.id, createToolResponse(JSON.stringify(result, null, 2)));
+      return;
+    }
+
+    sendResponse(request.id, createToolResponse(JSON.stringify(authStatus, null, 2)));
+  } catch (error) {
+    sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, `Failed to get auth status: ${error.message}`);
+  }
+}
+
+/**
+ * Handle auth_login_instructions tool
+ * @param {Object} request - JSON-RPC request
+ */
+function handleAuthLoginInstructions(request) {
+  const text = 'To authenticate, run the following command:\n\n```bash\nnpx @meldocio/mcp-stdio-proxy@latest auth login\n```';
+  sendResponse(request.id, createToolResponse(text));
+}
+
+/**
+ * Check if tool should be handled locally
+ * @param {string} toolName - Tool name
+ * @returns {boolean} True if local tool
+ */
+function isLocalTool(toolName) {
+  const localTools = [
+    'set_workspace',
+    'get_workspace',
+    'auth_status',
+    'auth_login_instructions'
+  ];
+  return localTools.includes(toolName);
+}
+
+/**
+ * Handle tools/call for local tools
+ * @param {Object} request - JSON-RPC request
+ * @returns {Promise<boolean>} True if handled locally, false if should be proxied
+ */
+async function handleToolsCall(request) {
+  const toolName = request.params?.name;
+  const arguments_ = request.params?.arguments || {};
+
+  log(LOG_LEVELS.DEBUG, `handleToolsCall: toolName=${toolName}`);
+
+  if (!isLocalTool(toolName)) {
+    return false; // Not a local tool, should be proxied
+  }
+
+  // Handle local tools
+  try {
+    switch (toolName) {
+      case 'set_workspace':
+        handleSetWorkspace(request, arguments_);
+        break;
+      case 'get_workspace':
+        handleGetWorkspace(request);
+        break;
+      case 'auth_status':
+        await handleAuthStatus(request);
+        break;
+      case 'auth_login_instructions':
+        handleAuthLoginInstructions(request);
+        break;
+    }
+    return true; // Handled
+  } catch (error) {
+    log(LOG_LEVELS.ERROR, `Unexpected error in handleToolsCall: ${error.message || 'Unknown error'}`);
+    sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR,
+              `Error executing tool: ${error.message || 'Unknown error'}`, {
+                code: 'INTERNAL_ERROR'
+              });
+    return true; // Error handled
+  }
+}
+
+module.exports = {
+  handleToolsCall,
+  isLocalTool
+};

package/lib/protocol/error-codes.js

@@ -0,0 +1,143 @@
+/**
+ * JSON-RPC and Custom Error Codes
+ *
+ * This module centralizes all error code definitions and error message formatting
+ * for the Meldoc MCP proxy.
+ */
+
+/**
+ * Standard JSON-RPC 2.0 error codes
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+const JSON_RPC_ERROR_CODES = {
+  PARSE_ERROR: -32700,      // Invalid JSON was received by the server
+  INVALID_REQUEST: -32600,  // The JSON sent is not a valid Request object
+  METHOD_NOT_FOUND: -32601, // The method does not exist / is not available
+  INVALID_PARAMS: -32602,   // Invalid method parameter(s)
+  INTERNAL_ERROR: -32603,   // Internal JSON-RPC error
+  SERVER_ERROR: -32000      // Generic server error (implementation-defined)
+};
+
+/**
+ * Custom application error codes
+ * Using the reserved range -32000 to -32099 for server errors
+ */
+const CUSTOM_ERROR_CODES = {
+  AUTH_REQUIRED: -32001,  // Authentication required but not provided
+  NOT_FOUND: -32002,      // Requested resource not found
+  RATE_LIMIT: -32003      // Rate limit exceeded
+};
+
+/**
+ * All error codes combined
+ */
+const ALL_ERROR_CODES = {
+  ...JSON_RPC_ERROR_CODES,
+  ...CUSTOM_ERROR_CODES
+};
+
+/**
+ * HTTP status code mappings for common errors
+ */
+const HTTP_STATUS_CODES = {
+  OK: 200,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  RATE_LIMITED: 429,
+  INTERNAL_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503
+};
+
+/**
+ * Get a human-readable error name from error code
+ * @param {number} code - The error code
+ * @returns {string} Error name or 'UNKNOWN_ERROR'
+ */
+function getErrorName(code) {
+  const entry = Object.entries(ALL_ERROR_CODES).find(([_, value]) => value === code);
+  return entry ? entry[0] : 'UNKNOWN_ERROR';
+}
+
+/**
+ * Check if an error code represents an authentication error
+ * @param {number} code - The error code
+ * @returns {boolean} True if authentication error
+ */
+function isAuthError(code) {
+  return code === CUSTOM_ERROR_CODES.AUTH_REQUIRED ||
+         code === HTTP_STATUS_CODES.UNAUTHORIZED ||
+         code === HTTP_STATUS_CODES.FORBIDDEN;
+}
+
+/**
+ * Check if an error code represents a client error (4xx)
+ * @param {number} code - The error code
+ * @returns {boolean} True if client error
+ */
+function isClientError(code) {
+  return code >= 400 && code < 500;
+}
+
+/**
+ * Check if an error code represents a server error (5xx)
+ * @param {number} code - The error code
+ * @returns {boolean} True if server error
+ */
+function isServerError(code) {
+  return code >= 500 && code < 600;
+}
+
+/**
+ * Format error message with additional context
+ * @param {string} message - Base error message
+ * @param {Object} details - Additional error details
+ * @returns {string} Formatted error message
+ */
+function formatErrorMessage(message, details = {}) {
+  let formatted = message;
+
+  if (details.code) {
+    formatted += ` (code: ${details.code})`;
+  }
+
+  if (details.hint) {
+    formatted += `\nHint: ${details.hint}`;
+  }
+
+  return formatted;
+}
+
+/**
+ * Create standard error data object
+ * @param {string} code - Error code identifier
+ * @param {string} [hint] - Optional hint for resolving the error
+ * @param {Object} [additional] - Additional error context
+ * @returns {Object} Error data object
+ */
+function createErrorData(code, hint = null, additional = {}) {
+  const data = {
+    code,
+    ...additional
+  };
+
+  if (hint) {
+    data.hint = hint;
+  }
+
+  return data;
+}
+
+module.exports = {
+  JSON_RPC_ERROR_CODES,
+  CUSTOM_ERROR_CODES,
+  ALL_ERROR_CODES,
+  HTTP_STATUS_CODES,
+  getErrorName,
+  isAuthError,
+  isClientError,
+  isServerError,
+  formatErrorMessage,
+  createErrorData
+};

package/lib/protocol/json-rpc.js

@@ -0,0 +1,183 @@
+/**
+ * JSON-RPC 2.0 Protocol Utilities
+ *
+ * Handles JSON-RPC response formatting and sending.
+ * Eliminates 8+ duplications of stdout write patterns throughout the codebase.
+ */
+
+const { LOG_LEVELS } = require('../core/constants');
+
+/**
+ * Get current log level from environment
+ */
+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();
+
+/**
+ * Send JSON-RPC success response
+ * @param {string|number} id - Request ID
+ * @param {any} result - Result data
+ */
+function sendResponse(id, result) {
+  if (id === undefined || id === null) {
+    // Notification - no response needed
+    return;
+  }
+
+  const response = {
+    jsonrpc: '2.0',
+    id: id,
+    result: result
+  };
+
+  writeResponse(response);
+}
+
+/**
+ * Send JSON-RPC error response
+ * @param {string|number} id - Request ID
+ * @param {number} code - Error code
+ * @param {string} message - Error message
+ * @param {Object} [details] - Optional error details
+ */
+function sendError(id, code, message, details) {
+  // Only send error response if id is defined (not for notifications)
+  // Claude Desktop's Zod schema doesn't accept null for id
+  if (id === undefined || id === null) {
+    // For notifications or parse errors without id, don't send response
+    return;
+  }
+
+  const errorResponse = {
+    jsonrpc: '2.0',
+    id: id,
+    error: {
+      code: code,
+      message: message
+    }
+  };
+
+  // Add details if provided and debug logging is enabled
+  if (details && LOG_LEVEL >= LOG_LEVELS.DEBUG) {
+    errorResponse.error.data = details;
+  }
+
+  writeResponse(errorResponse);
+}
+
+/**
+ * Write JSON-RPC response to stdout
+ * Handles flushing and error cases
+ * @param {Object} response - Response object to send
+ */
+function writeResponse(response) {
+  try {
+    const responseStr = JSON.stringify(response);
+    process.stdout.write(responseStr + '\n');
+
+    // Flush stdout to ensure data is sent immediately
+    if (process.stdout.isTTY) {
+      process.stdout.flush();
+    }
+  } catch (error) {
+    // If stdout write fails, we can't do much - just log to stderr
+    if (process.stderr) {
+      process.stderr.write(`Failed to write response: ${error.message}\n`);
+    }
+  }
+}
+
+/**
+ * Create a success response object (without sending)
+ * @param {string|number} id - Request ID
+ * @param {any} result - Result data
+ * @returns {Object} Response object
+ */
+function createResponse(id, result) {
+  return {
+    jsonrpc: '2.0',
+    id: id,
+    result: result
+  };
+}
+
+/**
+ * Create an error response object (without sending)
+ * @param {string|number} id - Request ID
+ * @param {number} code - Error code
+ * @param {string} message - Error message
+ * @param {Object} [details] - Optional error details
+ * @returns {Object} Error response object
+ */
+function createErrorResponse(id, code, message, details) {
+  const errorResponse = {
+    jsonrpc: '2.0',
+    id: id,
+    error: {
+      code: code,
+      message: message
+    }
+  };
+
+  if (details && LOG_LEVEL >= LOG_LEVELS.DEBUG) {
+    errorResponse.error.data = details;
+  }
+
+  return errorResponse;
+}
+
+/**
+ * Validate JSON-RPC request structure
+ * @param {any} request - Request to validate
+ * @returns {Object} { valid: boolean, error?: string }
+ */
+function validateRequest(request) {
+  if (!request || typeof request !== 'object') {
+    return { valid: false, error: 'Request must be an object' };
+  }
+
+  // Allow requests without jsonrpc for compatibility
+  if (request.jsonrpc && request.jsonrpc !== '2.0') {
+    return { valid: false, error: 'jsonrpc must be "2.0"' };
+  }
+
+  // Allow requests without method if they're notifications
+  if (!request.method && !Array.isArray(request) && request.id !== null && request.id !== undefined) {
+    return { valid: false, error: 'Request must have a method or be a batch array' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Check if a request is a notification (no id)
+ * @param {Object} request - Request object
+ * @returns {boolean} True if notification
+ */
+function isNotification(request) {
+  return request.id === null || request.id === undefined;
+}
+
+/**
+ * Extract method name from request
+ * @param {Object} request - Request object
+ * @returns {string|null} Method name or null
+ */
+function getMethodName(request) {
+  return request && request.method ? request.method : null;
+}
+
+module.exports = {
+  sendResponse,
+  sendError,
+  writeResponse,
+  createResponse,
+  createErrorResponse,
+  validateRequest,
+  isNotification,
+  getMethodName
+};