@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/mcp/factory.js

@@ -0,0 +1,161 @@
+/**
+ * NeuroLink MCP Server Factory
+ * Factory-First Architecture: MCP servers create tools for internal orchestration
+ * Compatible with MCP patterns for seamless integration
+ */
+import { z } from "zod";
+import { validateMCPTool, ValidationError, createValidationSummary, } from "../utils/parameterValidation.js";
+/**
+ * Input validation schemas
+ */
+const ServerConfigSchema = z.object({
+    id: z.string().min(1, "Server ID is required"),
+    title: z.string().min(1, "Server title is required"),
+    description: z.string().optional(),
+    version: z.string().optional(),
+    category: z
+        .enum([
+        "aiProviders",
+        "frameworks",
+        "development",
+        "business",
+        "content",
+        "data",
+        "integrations",
+        "automation",
+        "analysis",
+        "custom",
+    ])
+        .optional(),
+    visibility: z.enum(["public", "private", "organization"]).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    dependencies: z.array(z.string()).optional(),
+    capabilities: z.array(z.string()).optional(),
+});
+/**
+ * Create MCP Server Factory Function
+ *
+ * Core factory function for creating MCP servers.
+ * Follows Factory-First architecture where tools are internal implementation.
+ *
+ * @param config Server configuration with minimal required fields
+ * @returns Fully configured MCP server ready for tool registration
+ *
+ * @example
+ * ```typescript
+ * const aiCoreServer = createMCPServer({
+ *   id: 'neurolink-ai-core',
+ *   title: 'NeuroLink AI Core',
+ *   description: 'Core AI provider tools',
+ *   category: 'aiProviders'
+ * });
+ *
+ * aiCoreServer.registerTool({
+ *   name: 'generate',
+ *   description: 'Generate text using AI providers',
+ *   execute: async (params, context) => {
+ *     // Tool implementation
+ *     return { success: true, data: result };
+ *   }
+ * });
+ * ```
+ */
+export function createMCPServer(config) {
+    // Validate configuration
+    const validatedConfig = ServerConfigSchema.parse(config);
+    // Create server with sensible defaults
+    const server = {
+        // Required fields
+        id: validatedConfig.id,
+        title: validatedConfig.title,
+        // Optional fields with defaults
+        description: validatedConfig.description,
+        version: validatedConfig.version || "1.0.0",
+        category: validatedConfig.category || "custom",
+        visibility: validatedConfig.visibility || "private",
+        // Tool management
+        tools: {},
+        // Tool registration method
+        registerTool(tool) {
+            // Comprehensive tool validation using centralized utilities
+            const validation = validateMCPTool(tool);
+            if (!validation.isValid) {
+                const summary = createValidationSummary(validation);
+                throw new ValidationError(`Invalid tool '${tool.name}': ${summary}`, "tool", "VALIDATION_FAILED", validation.suggestions);
+            }
+            // Check for duplicate tool names
+            if (this.tools[tool.name]) {
+                throw new Error(`Tool '${tool.name}' already exists in server '${this.id}'`);
+            }
+            // Register the tool
+            this.tools[tool.name] = {
+                ...tool,
+                // Add server metadata to tool
+                metadata: {
+                    ...tool.metadata,
+                    serverId: this.id,
+                    serverCategory: this.category,
+                    registeredAt: Date.now(),
+                },
+            };
+            return this;
+        },
+        // Extension points
+        metadata: validatedConfig.metadata || {},
+        dependencies: validatedConfig.dependencies || [],
+        capabilities: validatedConfig.capabilities || [],
+    };
+    return server;
+}
+/**
+ * Utility function to validate tool interface using centralized validation
+ * Ensures proper async patterns and type safety
+ */
+export function validateTool(tool) {
+    try {
+        const validation = validateMCPTool(tool);
+        return validation.isValid;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Utility function to get server info
+ */
+export function getServerInfo(server) {
+    return {
+        id: server.id,
+        title: server.title,
+        description: server.description,
+        category: server.category,
+        toolCount: Object.keys(server.tools).length,
+        capabilities: server.capabilities || [],
+    };
+}
+/**
+ * Async utility function to validate all tools in a server
+ * Ensures all registered tools follow proper async patterns
+ */
+export async function validateServerTools(server) {
+    const invalidTools = [];
+    const errors = [];
+    for (const [toolName, tool] of Object.entries(server.tools)) {
+        try {
+            if (!validateTool(tool)) {
+                invalidTools.push(toolName);
+                errors.push(`Tool '${toolName}' does not follow proper async patterns`);
+            }
+        }
+        catch (error) {
+            invalidTools.push(toolName);
+            errors.push(`Tool '${toolName}' validation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        isValid: invalidTools.length === 0,
+        invalidTools,
+        errors,
+    };
+}
+// Types are already exported above via export interface declarations

package/dist/client/mcp/flexibleToolValidator.js

@@ -0,0 +1,161 @@
+/**
+ * FlexibleToolValidator - Universal Safety Checks Only
+ *
+ * Following Anthropic's MCP specification which intentionally leaves tool naming flexible,
+ * this validator only blocks truly dangerous cases to support maximum MCP tool compatibility.
+ *
+ * Phase 1 Implementation:
+ * - Universal safety checks only (empty names, control characters, excessive length)
+ * - No context-specific validation or arbitrary pattern restrictions
+ * - Designed to support ALL legitimate MCP tools (github.create_repo, filesystem.read_file, etc.)
+ */
+import { registryLogger } from "../utils/logger.js";
+export class FlexibleToolValidator {
+    // Universal safety limits (generous to support all legitimate tools)
+    static MAX_TOOL_NAME_LENGTH = 1000; // Much more generous than npm's 214
+    static MIN_TOOL_NAME_LENGTH = 1;
+    /**
+     * Validate tool name with universal safety checks only
+     *
+     * This method only blocks truly dangerous cases:
+     * 1. Empty or whitespace-only names
+     * 2. Control characters that could break systems
+     * 3. Excessively long names that could cause memory issues
+     *
+     * Everything else is allowed to support maximum MCP tool compatibility.
+     */
+    static validateToolName(toolId) {
+        const warnings = [];
+        // Safety Check 1: Empty or whitespace-only names
+        if (!toolId || typeof toolId !== "string") {
+            return {
+                isValid: false,
+                error: "Tool name is required and must be a string",
+            };
+        }
+        // Safety Check 2: Control characters that could break systems (check BEFORE trimming!)
+        // Only block truly dangerous control characters, not printable characters
+        //
+        // This regex blocks dangerous C0 control characters and DEL:
+        // - \x00-\x08: NULL, SOH, STX, ETX, EOT, ENQ, ACK, BEL, BS
+        // - \x0B: Vertical Tab (VT)
+        // - \x0C: Form Feed (FF)
+        // - \x0E-\x1F: SO, SI, DLE, DC1-4, NAK, SYN, ETB, CAN, EM, SUB, ESC, FS-US
+        // - \x7F: DEL
+        //
+        // Explicitly ALLOWS these printable control characters:
+        // - \x09: TAB (horizontal tab) - commonly used in text
+        // - \x0A: LF (line feed) - commonly used in text
+        // - \x0D: CR (carriage return) - commonly used in text
+        // eslint-disable-next-line no-control-regex
+        const hasControlCharacters = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/.test(toolId);
+        if (hasControlCharacters) {
+            return {
+                isValid: false,
+                error: "Tool name contains control characters that could break systems",
+            };
+        }
+        const trimmedName = toolId.trim();
+        if (trimmedName.length === 0) {
+            return {
+                isValid: false,
+                error: "Tool name cannot be empty or whitespace-only",
+            };
+        }
+        // Safety Check 3: Length limits (very generous)
+        if (trimmedName.length < this.MIN_TOOL_NAME_LENGTH) {
+            return {
+                isValid: false,
+                error: `Tool name must be at least ${this.MIN_TOOL_NAME_LENGTH} character long`,
+            };
+        }
+        if (trimmedName.length > this.MAX_TOOL_NAME_LENGTH) {
+            return {
+                isValid: false,
+                error: `Tool name exceeds maximum length of ${this.MAX_TOOL_NAME_LENGTH} characters`,
+            };
+        }
+        // Optional warnings for unusual but not dangerous patterns
+        if (trimmedName !== toolId) {
+            warnings.push("Tool name has leading/trailing whitespace (will be trimmed)");
+        }
+        if (trimmedName.length > 200) {
+            warnings.push("Tool name is unusually long but allowed");
+        }
+        registryLogger.debug(`✅ FlexibleToolValidator: Tool '${toolId}' passed universal safety checks`);
+        return {
+            isValid: true,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    /**
+     * Validate tool information with minimal safety checks
+     */
+    static validateToolInfo(toolId, toolInfo) {
+        // First validate the tool name
+        const nameValidation = this.validateToolName(toolId);
+        if (!nameValidation.isValid) {
+            return nameValidation;
+        }
+        const warnings = [...(nameValidation.warnings || [])];
+        // Minimal safety checks for tool info
+        if (toolInfo.description && typeof toolInfo.description !== "string") {
+            return {
+                isValid: false,
+                error: "Tool description must be a string if provided",
+            };
+        }
+        if (toolInfo.serverId && typeof toolInfo.serverId !== "string") {
+            return {
+                isValid: false,
+                error: "Tool serverId must be a string if provided",
+            };
+        }
+        registryLogger.debug(`✅ FlexibleToolValidator: Tool info for '${toolId}' passed validation`);
+        return {
+            isValid: true,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    /**
+     * Get information about what this validator checks
+     */
+    static getValidationInfo() {
+        return {
+            philosophy: "Maximum flexibility with universal safety only - following Anthropic's MCP specification",
+            checks: [
+                "Empty or whitespace-only names",
+                "Excessive length (over 1000 characters)",
+                "Control characters that could break systems",
+            ],
+            whatIsAllowed: [
+                "Dots (github.create_repo, filesystem.read_file)",
+                "Hyphens and underscores (my-tool, user_helper)",
+                "Numbers (tool1, my_tool_v2)",
+                "Unicode characters (🚀_tool, café_manager)",
+                "Mixed case (createRepo, ReadFile)",
+                "Long descriptive names (enterprise_database_connection_manager)",
+                "Any legitimate MCP tool naming pattern",
+            ],
+            examples: {
+                valid: [
+                    "github.create_repo",
+                    "filesystem.read_file",
+                    "my-custom-tool",
+                    "user_helper",
+                    "tool1",
+                    "🚀_rocket_tool",
+                    "enterprise.database.connection.manager",
+                    "UPPERCASE_TOOL",
+                    "mixed_Case.Tool-Name_123",
+                ],
+                invalid: [
+                    "", // Empty
+                    "   ", // Whitespace only
+                    "tool\x00", // Control character
+                    "a".repeat(1001), // Too long
+                ],
+            },
+        };
+    }
+}