converse-mcp-server 1.0.1

package/src/router.js

@@ -0,0 +1,497 @@
+/**
+ * Central Request Router
+ *
+ * Single orchestration point that dispatches MCP requests to tools with dependency injection.
+ * Handles tool lookup, error management, and consistent response formatting.
+ * Follows functional architecture with comprehensive error handling.
+ */
+
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { getContinuationStore } from './continuationStore.js';
+import { getTools } from './tools/index.js';
+import { getProviders } from './providers/index.js';
+import { processUnifiedContext } from './utils/contextProcessor.js';
+import { createLogger, startTimer } from './utils/logger.js';
+import { debugError } from './utils/console.js';
+import { 
+  ConverseMCPError, 
+  ToolError, 
+  ValidationError,
+  createMCPErrorResponse,
+  withErrorHandler,
+  ERROR_CODES
+} from './utils/errorHandler.js';
+
+const logger = createLogger('router');
+
+/**
+ * Router-specific error class
+ */
+export class RouterError extends ConverseMCPError {
+  constructor(message, code = ERROR_CODES.ROUTER_ERROR, details = {}) {
+    super(message, code, details, 500);
+    this.name = 'RouterError';
+  }
+}
+
+/**
+ * Standard error response format for consistent error handling
+ * @param {Error} error - The error that occurred
+ * @param {string} toolName - Name of the tool that failed
+ * @param {object} context - Additional context information
+ * @returns {object} Standardized error response
+ */
+export function createErrorResponse(error, toolName = 'unknown', context = {}) {
+  return createMCPErrorResponse(error, toolName, context);
+}
+
+/**
+ * Validate tool exists and is callable
+ * @param {string} toolName - Name of the tool to validate
+ * @param {object} tools - Available tools registry
+ * @returns {object} Validation result
+ */
+function validateTool(toolName, tools) {
+  if (!toolName || typeof toolName !== 'string') {
+    throw new RouterError(
+      'Tool name must be a non-empty string',
+      'INVALID_TOOL_NAME'
+    );
+  }
+
+  if (!tools[toolName]) {
+    const availableTools = Object.keys(tools);
+    throw new RouterError(
+      `Tool error: Unknown tool '${toolName}'. Available tools: ${availableTools.join(', ')}`,
+      'UNKNOWN_TOOL',
+      { requestedTool: toolName, availableTools }
+    );
+  }
+
+  if (typeof tools[toolName] !== 'function') {
+    throw new RouterError(
+      `Tool ${toolName} is not callable`,
+      'INVALID_TOOL_HANDLER',
+      { toolName, toolType: typeof tools[toolName] }
+    );
+  }
+
+  return {
+    isValid: true,
+    tool: tools[toolName]
+  };
+}
+
+/**
+ * Enhanced dependency injection with error handling
+ * @param {object} config - Configuration object
+ * @returns {object} Dependencies object for tool injection
+ */
+async function createDependencies(config) {
+  try {
+    const continuationStore = getContinuationStore();
+    const tools = getTools();
+    const providers = getProviders();
+
+    // Validate that we have the necessary dependencies
+    if (!continuationStore) {
+      throw new RouterError(
+        'Failed to initialize continuation store',
+        'DEPENDENCY_ERROR'
+      );
+    }
+
+    if (!tools || Object.keys(tools).length === 0) {
+      throw new RouterError(
+        'No tools available - tools registry is empty',
+        'NO_TOOLS_AVAILABLE'
+      );
+    }
+
+    if (!providers || Object.keys(providers).length === 0) {
+      throw new RouterError(
+        'No providers available - providers registry is empty',
+        'NO_PROVIDERS_AVAILABLE'
+      );
+    }
+
+    return {
+      config,
+      continuationStore,
+      providers,
+      contextProcessor: { processUnifiedContext },
+      router: {
+        createErrorResponse,
+        validateToolArguments,
+      },
+    };
+
+  } catch (error) {
+    debugError('Failed to create dependencies:', error);
+    throw error;
+  }
+}
+
+/**
+ * Creates and configures the central router for handling MCP requests
+ * @param {object} server - MCP Server instance
+ * @param {object} config - Configuration object with provider settings
+ * @returns {Promise<void>}
+ */
+export async function createRouter(server, config) {
+  const createRouterLogger = logger.operation('createRouter');
+  const timer = startTimer('router-initialization', 'router');
+  
+  try {
+    createRouterLogger.info('Initializing router');
+    
+    // Initialize dependencies with validation
+    const dependencies = await createDependencies(config);
+    const tools = getTools();
+
+    createRouterLogger.info(`Router initialized with ${Object.keys(tools).length} tools`);
+
+    // Register unified tool call handler with enhanced error handling
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const toolTimer = startTimer('tool-execution', 'router');
+      const toolName = request.params?.name;
+      const toolArgs = request.params?.arguments || {};
+      const requestLogger = logger.operation(`tool-call:${toolName}`);
+
+      try {
+        requestLogger.info('Tool execution started', { 
+          data: { toolName, argCount: Object.keys(toolArgs).length } 
+        });
+
+        // Validate tool existence and callability
+        const { tool } = validateTool(toolName, tools);
+
+        // Validate tool arguments if schema is provided
+        if (tool.inputSchema) {
+          const isValidArgs = validateToolArguments(toolArgs, tool.inputSchema);
+          if (!isValidArgs) {
+            throw new ValidationError(
+              `Invalid arguments for tool ${toolName}`,
+              ERROR_CODES.INVALID_TOOL_ARGS,
+              {
+                providedArgs: Object.keys(toolArgs),
+                expectedSchema: tool.inputSchema
+              }
+            );
+          }
+        }
+
+        // Execute the tool with dependency injection
+        const result = await tool(toolArgs, dependencies);
+
+        const executionTime = toolTimer('completed');
+        requestLogger.info('Tool execution completed', { 
+          data: { executionTime: `${executionTime}ms` } 
+        });
+
+        // Ensure result has proper format
+        if (!result || !result.content) {
+          throw new ToolError(
+            `Tool ${toolName} returned invalid result format`,
+            ERROR_CODES.TOOL_EXECUTION_FAILED,
+            { result },
+            toolName
+          );
+        }
+
+        return result;
+
+      } catch (error) {
+        const executionTime = toolTimer('failed');
+        requestLogger.error('Tool execution failed', { 
+          error,
+          data: { executionTime: `${executionTime}ms`, argCount: Object.keys(toolArgs).length }
+        });
+
+        return createErrorResponse(error, toolName, {
+          executionTime,
+          arguments: Object.keys(toolArgs),
+          requestId: request.id || 'unknown'
+        });
+      }
+    });
+
+    // Register enhanced list_tools handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+      try {
+        const toolList = Object.entries(tools).map(([name, handler]) => {
+          const toolInfo = {
+            name,
+            description: handler.description || `${name} tool - no description provided`,
+            inputSchema: handler.inputSchema || {
+              type: 'object',
+              properties: {},
+              description: 'No input schema defined'
+            },
+          };
+
+          // Add additional metadata if available
+          if (handler.version) {
+            toolInfo.version = handler.version;
+          }
+          if (handler.category) {
+            toolInfo.category = handler.category;
+          }
+
+          return toolInfo;
+        });
+
+        return {
+          tools: toolList,
+          metadata: {
+            totalTools: toolList.length,
+            timestamp: new Date().toISOString(),
+            routerVersion: '1.0.0'
+          }
+        };
+
+      } catch (error) {
+        debugError('Error listing tools:', error);
+        throw new RouterError(
+          'Failed to list available tools',
+          'TOOLS_LIST_ERROR',
+          { error: error.message }
+        );
+      }
+    });
+
+    // Note: Custom health endpoint removed - MCP uses standard protocol methods only
+
+    timer('completed');
+    createRouterLogger.info('Router configured successfully', {
+      data: {
+        tools: Object.keys(tools).length,
+        providers: Object.keys(dependencies.providers).length,
+        continuationStore: dependencies.continuationStore.constructor.name,
+        environment: config.environment.nodeEnv
+      }
+    });
+
+    // Return router interface for testing purposes
+    return {
+      listTools: async () => {
+        const tools = getTools();
+        return {
+          tools: Object.entries(tools).map(([name, tool]) => {
+            const toolSchema = {
+              name,
+              description: tool.description || 'No description available'
+            };
+
+            if (tool.inputSchema) {
+              toolSchema.inputSchema = tool.inputSchema;
+            }
+
+            return toolSchema;
+          })
+        };
+      },
+      
+      callTool: async (toolCall) => {
+        const toolName = toolCall.name;
+        const toolArgs = toolCall.arguments || {};
+        
+        try {
+          // Validate tool existence and callability
+          const { tool } = validateTool(toolName, tools);
+
+          // Validate tool arguments if schema is provided
+          if (tool.inputSchema) {
+            const isValidArgs = validateToolArguments(toolArgs, tool.inputSchema);
+            if (!isValidArgs) {
+              throw new ValidationError(
+                `Invalid arguments for tool ${toolName}`,
+                ERROR_CODES.INVALID_TOOL_ARGS,
+                {
+                  providedArgs: Object.keys(toolArgs),
+                  expectedSchema: tool.inputSchema
+                }
+              );
+            }
+          }
+
+          // Execute the tool with dependency injection
+          return await tool(toolArgs, dependencies);
+        } catch (error) {
+          return createErrorResponse(error, toolName, {
+            arguments: toolArgs,
+            executionTime: 0,
+            requestId: 'test'
+          });
+        }
+      }
+    };
+
+  } catch (error) {
+    timer('failed');
+    createRouterLogger.error('Router initialization failed', { error });
+    throw new RouterError(
+      'Router initialization failed',
+      ERROR_CODES.ROUTER_ERROR,
+      { originalError: error.message }
+    );
+  }
+}
+
+/**
+ * Get JSON Schema type for a JavaScript value
+ * @param {any} value - The value to get type for
+ * @returns {string} JSON Schema type
+ */
+function getJsonSchemaType(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? 'integer' : 'number';
+  }
+  return typeof value;
+}
+
+/**
+ * Check if a JavaScript value matches a JSON Schema type
+ * @param {any} value - The value to check
+ * @param {string} schemaType - The JSON Schema type to check against
+ * @returns {boolean} True if value matches the schema type
+ */
+function isValidJsonSchemaType(value, schemaType) {
+  if (schemaType === 'null') return value === null;
+  if (schemaType === 'array') return Array.isArray(value);
+  if (schemaType === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (schemaType === 'boolean') return typeof value === 'boolean';
+  if (schemaType === 'string') return typeof value === 'string';
+  if (schemaType === 'number') return typeof value === 'number';
+  if (schemaType === 'integer') return typeof value === 'number' && Number.isInteger(value);
+  
+  // For unknown types, fall back to JavaScript typeof
+  return typeof value === schemaType;
+}
+
+/**
+ * Enhanced tool argument validation against schema
+ * @param {object} args - Tool arguments to validate
+ * @param {object} schema - JSON schema for validation
+ * @returns {boolean} True if arguments are valid
+ * @throws {RouterError} If validation fails with details
+ */
+export function validateToolArguments(args, schema) {
+  try {
+    // If no schema provided, assume valid
+    if (!schema) {
+      return true;
+    }
+
+    // Basic type checking
+    if (schema.type === 'object' && (typeof args !== 'object' || args === null)) {
+      throw new RouterError(
+        'Arguments must be an object',
+        'INVALID_ARGUMENT_TYPE',
+        { expected: 'object', received: typeof args }
+      );
+    }
+
+    // Check required properties
+    if (schema.required && Array.isArray(schema.required)) {
+      const missing = schema.required.filter(key => !(key in args));
+      if (missing.length > 0) {
+        throw new RouterError(
+          `Validation error: Missing required arguments: ${missing.join(', ')}`,
+          'MISSING_REQUIRED_ARGS',
+          { missing, provided: Object.keys(args) }
+        );
+      }
+    }
+
+    // Validate individual properties
+    if (schema.properties) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in args) {
+          const value = args[key];
+
+          // Basic type validation using JSON Schema type semantics
+          if (propSchema.type && !isValidJsonSchemaType(value, propSchema.type)) {
+            const actualType = getJsonSchemaType(value);
+            throw new RouterError(
+              `Argument '${key}' must be of type ${propSchema.type}`,
+              'INVALID_ARGUMENT_TYPE',
+              {
+                argument: key,
+                expected: propSchema.type,
+                received: actualType
+              }
+            );
+          }
+
+          // String length validation
+          if (propSchema.type === 'string') {
+            if (propSchema.minLength && value.length < propSchema.minLength) {
+              throw new RouterError(
+                `Argument '${key}' must be at least ${propSchema.minLength} characters`,
+                'ARGUMENT_TOO_SHORT',
+                { argument: key, minLength: propSchema.minLength, actual: value.length }
+              );
+            }
+            if (propSchema.maxLength && value.length > propSchema.maxLength) {
+              throw new RouterError(
+                `Argument '${key}' must be at most ${propSchema.maxLength} characters`,
+                'ARGUMENT_TOO_LONG',
+                { argument: key, maxLength: propSchema.maxLength, actual: value.length }
+              );
+            }
+          }
+        }
+      }
+    }
+
+    return true;
+
+  } catch (error) {
+    if (error instanceof RouterError) {
+      throw error;
+    }
+    throw new RouterError(
+      `Argument validation failed: ${error.message}`,
+      'VALIDATION_ERROR',
+      { originalError: error.message }
+    );
+  }
+}
+
+/**
+ * Get router statistics and health information
+ * @param {object} dependencies - Router dependencies
+ * @returns {Promise<object>} Router statistics
+ */
+export async function getRouterStats(dependencies) {
+  try {
+    const tools = getTools();
+    const storeStats = await dependencies.continuationStore.getStats();
+
+    return {
+      timestamp: new Date().toISOString(),
+      uptime: process.uptime(),
+      tools: {
+        count: Object.keys(tools).length,
+        available: Object.keys(tools)
+      },
+      providers: {
+        count: Object.keys(dependencies.providers).length,
+        available: Object.keys(dependencies.providers)
+      },
+      continuationStore: storeStats,
+      memory: process.memoryUsage(),
+      environment: dependencies.config.environment.nodeEnv
+    };
+
+  } catch (error) {
+    throw new RouterError(
+      'Failed to get router statistics',
+      'STATS_ERROR',
+      { error: error.message }
+    );
+  }
+}

package/src/systemPrompts.js

@@ -0,0 +1,90 @@
+/**
+ * System Prompts for Converse MCP Server Tools
+ * 
+ * Matches the Python implementation system prompts exactly for feature parity.
+ */
+
+/**
+ * Chat tool system prompt - matches Python systemprompts/chat_prompt.py
+ */
+export const CHAT_PROMPT = `
+You are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,
+and offer well-reasoned second opinions on technical decisions when they are justified and practical.
+
+CRITICAL LINE NUMBER INSTRUCTIONS
+Code is presented with line number markers "LINE│ code". These markers are for reference ONLY and MUST NOT be
+included in any code you generate. Always reference specific line numbers in your replies in order to locate
+exact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.
+Include context_start_text and context_end_text as backup references. Never include "LINE│" markers in generated code
+snippets.
+
+IF MORE INFORMATION IS NEEDED
+If the agent is discussing specific code, functions, or project components that was not given as part of the context,
+and you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful
+collaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been
+provided unless for some reason its content is missing or incomplete:
+{
+  "status": "files_required_to_continue",
+  "mandatory_instructions": "<your critical instructions for the agent>",
+  "files_needed": ["[file name here]", "[or some folder/]"]
+}
+
+CORE PRINCIPLES
+• Work within the existing tech stack and architecture
+• Avoid overengineering - prefer simple, practical solutions
+• Focus on current scope, not speculative future needs
+• Provide concrete, actionable recommendations with clear trade-offs
+• Surface potential issues early and challenge assumptions constructively
+`.trim();
+
+/**
+ * Consensus tool system prompt - matches Python systemprompts/consensus_prompt.py
+ */
+export const CONSENSUS_PROMPT = `
+You're analyzing a technical problem alongside other AI models. Each model will propose solutions independently, then potentially see others' approaches.
+
+Your goal: Find the best solution, whether it's yours or another model's. The key is often a single insight that makes everything click.
+
+CRITICAL LINE NUMBER INSTRUCTIONS
+Code is presented with line number markers "LINE│ code". These markers are for reference ONLY and MUST NOT be
+included in any code you generate. Always reference specific line numbers in your replies in order to locate
+exact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.
+Never include "LINE│" markers in generated code snippets.
+
+IF MORE INFORMATION IS NEEDED
+If you need to see specific code, files, or technical context to properly analyze the problem, respond with this exact JSON:
+{
+  "status": "files_required_to_continue",
+  "mandatory_instructions": "<your critical instructions for the agent>",
+  "files_needed": ["[file name here]", "[or some folder/]"]
+}
+
+MANDATORY RESPONSE FORMAT
+You MUST respond in exactly this Markdown structure:
+
+## Approach
+Present your solution and the key insight behind it. Be direct and clear about what makes your approach work.
+If you're reviewing others' solutions, you'll do that in a later phase.
+
+## Why This Works
+Explain the technical reasoning. Be specific about why this approach solves the problem effectively.
+What's the core mechanism or principle that makes it succeed?
+
+## Implementation
+Provide concrete code or steps if relevant. Show exactly how to implement your approach.
+Focus on clarity and correctness.
+
+## Trade-offs
+What are the limitations or considerations? Be honest about where this approach might struggle
+or what alternatives might be better in certain contexts.
+
+QUALITY STANDARDS
+- Focus on finding the most elegant solution
+- Look for the key insight that simplifies the problem
+- Be direct - don't hedge unnecessarily
+- Value clarity and simplicity
+- Consider edge cases and robustness
+- Stay technical and grounded
+
+Remember: The best solution often has one breakthrough insight that makes the complexity fall away.
+`.trim();