@gavdi/cap-mcp 0.9.0 → 0.9.2

package/lib/mcp/session-manager.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpSessionManager = void 0;
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const crypto_1 = require("crypto");
+const env_sanitizer_1 = require("../config/env-sanitizer");
+const logger_1 = require("../logger");
+const factory_1 = require("./factory");
+/**
+ * Manages active MCP server sessions and their lifecycle
+ * Handles session creation, storage, retrieval, and cleanup for MCP protocol communication
+ */
+class McpSessionManager {
+    /** Map storing active sessions by their unique session IDs */
+    sessions;
+    /**
+     * Creates a new session manager with empty session storage
+     */
+    constructor() {
+        this.sessions = new Map();
+    }
+    /**
+     * Retrieves the complete map of active sessions
+     * @returns Map of session IDs to their corresponding session objects
+     */
+    getSessions() {
+        return this.sessions;
+    }
+    /**
+     * Checks if a session exists for the given session ID
+     * @param sessionID - Unique identifier for the session
+     * @returns True if session exists, false otherwise
+     */
+    hasSession(sessionID) {
+        return this.sessions.has(sessionID);
+    }
+    /**
+     * Retrieves a specific session by its ID
+     * @param sessionID - Unique identifier for the session
+     * @returns Session object if found, undefined otherwise
+     */
+    getSession(sessionID) {
+        return this.sessions.get(sessionID);
+    }
+    /**
+     * Creates a new MCP session with server and transport configuration
+     * Initializes MCP server with provided annotations and establishes transport connection
+     * @param config - CAP configuration for the MCP server
+     * @param annotations - Optional parsed MCP annotations for resources, tools, and prompts
+     * @returns Promise resolving to the created session object
+     */
+    async createSession(config, annotations) {
+        logger_1.LOGGER.debug("Initialize session request received");
+        const server = (0, factory_1.createMcpServer)(config, annotations);
+        const transport = this.createTransport(server);
+        await server.connect(transport);
+        return { server, transport };
+    }
+    /**
+     * Creates and configures HTTP transport for MCP communication
+     * Sets up session ID generation, response format, and event handlers
+     * @param server - MCP server instance to associate with the transport
+     * @returns Configured StreamableHTTPServerTransport instance
+     */
+    createTransport(server) {
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+            sessionIdGenerator: () => (0, crypto_1.randomUUID)(),
+            enableJsonResponse: (0, env_sanitizer_1.isTestEnvironment)(),
+            onsessioninitialized: (sid) => {
+                logger_1.LOGGER.debug("Session initialized with ID: ", sid);
+                this.sessions.set(sid, {
+                    server: server,
+                    transport: transport,
+                });
+            },
+        });
+        transport.onclose = () => this.onCloseSession(transport);
+        return transport;
+    }
+    /**
+     * Handles session cleanup when transport connection closes
+     * Removes the session from active sessions map when connection terminates
+     * @param transport - Transport instance that was closed
+     */
+    onCloseSession(transport) {
+        if (!transport.sessionId || !this.sessions.has(transport.sessionId)) {
+            return;
+        }
+        this.sessions.delete(transport.sessionId);
+    }
+}
+exports.McpSessionManager = McpSessionManager;

package/lib/mcp/tools.js

@@ -4,11 +4,14 @@ exports.assignToolToServer = assignToolToServer;
 const utils_1 = require("./utils");
 const logger_1 = require("../logger");
 const constants_1 = require("./constants");
+const zod_1 = require("zod");
 /* @ts-ignore */
 const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
 /**
- * Assigns the annotated tool to the server.
- * This is done by reference, and will therefore mutate the provided server.
+ * Registers a CAP function or action as an executable MCP tool
+ * Handles both bound (entity-level) and unbound (service-level) operations
+ * @param model - The tool annotation containing operation metadata and parameters
+ * @param server - The MCP server instance to register the tool with
  */
 function assignToolToServer(model, server) {
     logger_1.LOGGER.debug("Adding tool", model);
@@ -21,7 +24,11 @@ function assignToolToServer(model, server) {
     assignUnboundOperation(parameters, model, server);
 }
 /**
- * Creates tool handler for bound action/function imports
+ * Registers a bound operation that operates on a specific entity instance
+ * Requires entity key parameters in addition to operation parameters
+ * @param params - Zod schema definitions for operation parameters
+ * @param model - Tool annotation with bound operation metadata
+ * @param server - MCP server instance to register with
  */
 function assignBoundOperation(params, model, server) {
     if (!model.keyTypeMap || model.keyTypeMap.size <= 0) {
@@ -29,7 +36,12 @@ function assignBoundOperation(params, model, server) {
         throw new Error("Bound operation cannot be assigned to tool list, missing keys");
     }
     const keys = buildToolParameters(model.keyTypeMap);
-    server.registerTool(model.name, { ...keys, ...params }, async (data) => {
+    const inputSchema = buildZodSchema({ ...keys, ...params });
+    server.registerTool(model.name, {
+        title: model.name,
+        description: model.description,
+        inputSchema: inputSchema,
+    }, async (args) => {
         const service = cds.services[model.serviceName];
         if (!service) {
             logger_1.LOGGER.error("Invalid CAP service - undefined");
@@ -45,7 +57,7 @@ function assignBoundOperation(params, model, server) {
         }
         const operationInput = {};
         const operationKeys = {};
-        for (const [k, v] of Object.entries(data)) {
+        for (const [k, v] of Object.entries(args)) {
             if (model.keyTypeMap?.has(k)) {
                 operationKeys[k] = v;
             }
@@ -61,16 +73,28 @@ function assignBoundOperation(params, model, server) {
         });
         return {
             content: Array.isArray(response)
-                ? response.map((el) => ({ type: "text", text: String(el) }))
-                : [{ type: "text", text: String(response) }],
+                ? response.map((el) => ({
+                    type: "text",
+                    text: formatResponseValue(el),
+                }))
+                : [{ type: "text", text: formatResponseValue(response) }],
         };
     });
 }
 /**
- * Creates a tool handler for unbound action/function imports
+ * Registers an unbound operation that operates at the service level
+ * Does not require entity keys, only operation parameters
+ * @param params - Zod schema definitions for operation parameters
+ * @param model - Tool annotation with unbound operation metadata
+ * @param server - MCP server instance to register with
  */
 function assignUnboundOperation(params, model, server) {
-    server.registerTool(model.name, params, async (data) => {
+    const inputSchema = buildZodSchema(params);
+    server.registerTool(model.name, {
+        title: model.name,
+        description: model.description,
+        inputSchema: inputSchema,
+    }, async (args) => {
         const service = cds.services[model.serviceName];
         if (!service) {
             logger_1.LOGGER.error("Invalid CAP service - undefined");
@@ -84,16 +108,21 @@ function assignUnboundOperation(params, model, server) {
                 ],
             };
         }
-        const response = await service.send(model.target, data);
+        const response = await service.send(model.target, args);
         return {
             content: Array.isArray(response)
-                ? response.map((el) => ({ type: "text", text: String(el) }))
-                : [{ type: "text", text: String(response) }],
+                ? response.map((el) => ({
+                    type: "text",
+                    text: formatResponseValue(el),
+                }))
+                : [{ type: "text", text: formatResponseValue(response) }],
         };
     });
 }
 /**
- * Builds the parameters that the MCP server should take in for the given tool's parameters
+ * Converts a map of CDS parameter types to MCP parameter schema definitions
+ * @param params - Map of parameter names to their CDS type strings
+ * @returns Record of parameter names to Zod schema types
  */
 function buildToolParameters(params) {
     if (!params || params.size <= 0)
@@ -104,3 +133,43 @@ function buildToolParameters(params) {
     }
     return result;
 }
+/**
+ * Converts a value to a string representation suitable for MCP responses
+ * Handles objects and arrays by JSON stringifying them instead of using String()
+ * @param value - The value to convert to string
+ * @returns String representation of the value
+ */
+function formatResponseValue(value) {
+    if (value === null || value === undefined) {
+        return String(value);
+    }
+    if (typeof value === "object") {
+        try {
+            return JSON.stringify(value, null, 2);
+        }
+        catch (error) {
+            // Fallback to String() if JSON.stringify fails (e.g., circular references)
+            return String(value);
+        }
+    }
+    return String(value);
+}
+/**
+ * Constructs a complete Zod schema object for MCP tool input validation
+ * @param params - Record of parameter names to Zod schema types
+ * @returns Zod schema record suitable for MCP tool registration
+ */
+function buildZodSchema(params) {
+    const schema = {};
+    for (const [key, zodType] of Object.entries(params)) {
+        // The parameter is already a Zod type from determineMcpParameterType
+        if (zodType && typeof zodType === "object" && "describe" in zodType) {
+            schema[key] = zodType;
+        }
+        else {
+            // Fallback to string if not a valid Zod type
+            schema[key] = zod_1.z.string().describe(`Parameter: ${key}`);
+        }
+    }
+    return schema;
+}

package/lib/mcp/utils.js

@@ -6,7 +6,9 @@ exports.writeODataDescriptionForResource = writeODataDescriptionForResource;
 const constants_1 = require("./constants");
 const zod_1 = require("zod");
 /**
- * Takes in the string based type name of the CDS type found through CSN and converts it to zod type
+ * Converts a CDS type string to the corresponding Zod schema type
+ * @param cdsType - The CDS type name (e.g., 'String', 'Integer')
+ * @returns Zod schema instance for the given type
  */
 function determineMcpParameterType(cdsType) {
     switch (cdsType) {
@@ -19,8 +21,10 @@ function determineMcpParameterType(cdsType) {
     }
 }
 /**
- * Session handler for MCP server.
- * Rejects or approves incoming requests based on existing MCP session header ID
+ * Handles incoming MCP session requests by validating session IDs and routing to appropriate session
+ * @param req - Express request object containing session headers
+ * @param res - Express response object for sending responses
+ * @param sessions - Map of active MCP sessions keyed by session ID
  */
 async function handleMcpSessionRequest(req, res, sessions) {
     const sessionIdHeader = req.headers[constants_1.MCP_SESSION_HEADER];
@@ -35,6 +39,11 @@ async function handleMcpSessionRequest(req, res, sessions) {
     }
     await session.transport.handleRequest(req, res);
 }
+/**
+ * Writes a detailed OData description for a resource including available query parameters and properties
+ * @param model - The resource annotation to generate description for
+ * @returns Formatted description string with OData query syntax examples
+ */
 function writeODataDescriptionForResource(model) {
     let description = `${model.description}.${constants_1.NEW_LINE}`;
     description += `Should be queried using OData v4 query style using the following allowed parameters.${constants_1.NEW_LINE}`;

package/lib/mcp/validation.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ODataValidationError = exports.ODataQueryValidator = exports.ODataQueryValidationSchemas = void 0;
+const zod_1 = require("zod");
+const logger_1 = require("../logger");
+/**
+ * Comprehensive validation system for OData query parameters with security controls
+ * Provides schema validation, injection attack prevention, and type safety
+ */
+// Allowed OData operators
+const ALLOWED_OPERATORS = new Set([
+    "eq",
+    "ne",
+    "gt",
+    "ge",
+    "lt",
+    "le",
+    "and",
+    "or",
+    "not",
+    "contains",
+    "startswith",
+    "endswith",
+    "indexof",
+    "length",
+    "substring",
+    "tolower",
+    "toupper",
+    "trim",
+]);
+// Forbidden patterns that could indicate injection attempts
+const FORBIDDEN_PATTERNS = [
+    /;/g, // SQL statement terminator
+    /--/g, // SQL comment
+    /\/\*/g, // Multi-line comment start
+    /\*\//g, // Multi-line comment end
+    /xp_/gi, // Extended procedures
+    /sp_/gi, // Stored procedures
+    /exec/gi, // Execute command
+    /union/gi, // Union queries
+    /insert/gi, // Insert statements
+    /update/gi, // Update statements
+    /delete/gi, // Delete statements
+    /drop/gi, // Drop statements
+    /create/gi, // Create statements
+    /alter/gi, // Alter statements
+    /script/gi, // Script tags
+    /javascript/gi, // JavaScript
+    /eval/gi, // Eval function
+    /expression/gi, // Expression evaluation
+    /\bor\s+\d+\s*=\s*\d+/gi, // SQL injection pattern like \"OR 1=1\"
+    /\band\s+\d+\s*=\s*\d+/gi, // SQL injection pattern like \"AND 1=1\"
+];
+// Validation schemas
+exports.ODataQueryValidationSchemas = {
+    top: zod_1.z.number().int().min(1).max(1000),
+    skip: zod_1.z.number().int().min(0),
+    select: zod_1.z
+        .string()
+        .min(1)
+        .max(500)
+        .regex(/^[a-zA-Z_][a-zA-Z0-9_,\s]*$/),
+    orderby: zod_1.z
+        .string()
+        .min(1)
+        .max(200)
+        .regex(/^[a-zA-Z_][a-zA-Z0-9_\s]+(asc|desc)?(,\s*[a-zA-Z_][a-zA-Z0-9_\s]+(asc|desc)?)*$/i),
+    filter: zod_1.z.string().min(1).max(1000),
+};
+/**
+ * Validates and sanitizes OData query parameters with comprehensive security checks
+ * Prevents injection attacks, validates property references, and ensures type safety
+ */
+class ODataQueryValidator {
+    allowedProperties;
+    allowedTypes;
+    /**
+     * Creates a new OData query validator for a specific entity
+     * @param properties - Map of allowed entity properties to their CDS types
+     */
+    constructor(properties) {
+        this.allowedProperties = new Set(properties.keys());
+        this.allowedTypes = new Map(properties);
+    }
+    /**
+     * Validates and parses the $top query parameter
+     * @param value - String value of the $top parameter
+     * @returns Validated integer value between 1 and 1000
+     * @throws Error if value is invalid or out of range
+     */
+    validateTop(value) {
+        const parsed = parseFloat(value);
+        if (isNaN(parsed) || !Number.isInteger(parsed)) {
+            throw new Error(`Invalid top parameter: ${value}`);
+        }
+        return exports.ODataQueryValidationSchemas.top.parse(parsed);
+    }
+    /**
+     * Validates and parses the $skip query parameter
+     * @param value - String value of the $skip parameter
+     * @returns Validated non-negative integer value
+     * @throws Error if value is invalid or negative
+     */
+    validateSkip(value) {
+        const parsed = parseFloat(value);
+        if (isNaN(parsed) || !Number.isInteger(parsed)) {
+            throw new Error(`Invalid skip parameter: ${value}`);
+        }
+        return exports.ODataQueryValidationSchemas.skip.parse(parsed);
+    }
+    /**
+     * Validates and sanitizes the $select query parameter
+     * @param value - Comma-separated list of property names
+     * @returns Array of validated property names
+     * @throws Error if any property is invalid or not allowed
+     */
+    validateSelect(value) {
+        const decoded = decodeURIComponent(value);
+        const validated = exports.ODataQueryValidationSchemas.select.parse(decoded);
+        const columns = validated.split(",").map((col) => col.trim());
+        // Validate each column exists in entity
+        for (const column of columns) {
+            if (!this.allowedProperties.has(column)) {
+                throw new Error(`Invalid select column: ${column}. Allowed columns: ${Array.from(this.allowedProperties).join(", ")}`);
+            }
+        }
+        return columns;
+    }
+    /**
+     * Validates and sanitizes the $orderby query parameter
+     * @param value - Order by clause with property names and optional asc/desc
+     * @returns Validated order by string
+     * @throws Error if any property is invalid or not allowed
+     */
+    validateOrderBy(value) {
+        const decoded = decodeURIComponent(value);
+        const validated = exports.ODataQueryValidationSchemas.orderby.parse(decoded);
+        // Extract property names and validate they exist
+        const orderClauses = validated.split(",").map((clause) => clause.trim());
+        for (const clause of orderClauses) {
+            const parts = clause.split(/\s+/);
+            const property = parts[0];
+            if (!this.allowedProperties.has(property)) {
+                throw new Error(`Invalid orderby property: ${property}. Allowed properties: ${Array.from(this.allowedProperties).join(", ")}`);
+            }
+        }
+        return validated;
+    }
+    /**
+     * Validates and sanitizes the $filter query parameter with comprehensive security checks
+     * Prevents injection attacks, validates operators and property references
+     * @param value - OData filter expression
+     * @returns Sanitized filter string in CDS syntax
+     * @throws Error if filter contains forbidden patterns or invalid syntax
+     */
+    validateFilter(value) {
+        const input = value?.replace("filter=", "");
+        if (!input || input.trim().length === 0) {
+            throw new Error("Filter parameter cannot be empty");
+        }
+        const decoded = decodeURIComponent(input);
+        const validated = exports.ODataQueryValidationSchemas.filter.parse(decoded);
+        // Check for forbidden patterns
+        for (const pattern of FORBIDDEN_PATTERNS) {
+            if (pattern.test(validated)) {
+                logger_1.LOGGER.warn(`Potentially malicious filter pattern detected: ${pattern.source}`);
+                throw new Error("Filter contains forbidden patterns");
+            }
+        }
+        // Parse and validate filter structure
+        return this.parseAndValidateFilter(validated);
+    }
+    /**
+     * Parses OData filter expression and validates all components
+     * @param filter - Decoded and pre-validated filter string
+     * @returns CDS-compatible filter expression
+     */
+    parseAndValidateFilter(filter) {
+        // Tokenize the filter expression
+        const tokens = this.tokenizeFilter(filter);
+        // Validate tokens
+        this.validateFilterTokens(tokens);
+        // Convert OData operators to CDS syntax
+        return this.convertToCdsFilter(tokens);
+    }
+    /**
+     * Tokenizes filter expression into structured components for validation
+     * @param filter - Filter string to tokenize
+     * @returns Array of typed tokens representing the filter structure
+     */
+    tokenizeFilter(filter) {
+        const tokens = [];
+        // Enhanced tokenizer with OData operator support - literals first to avoid misclassification
+        const tokenRegex = /(\b(?:eq|ne|gt|ge|lt|le|contains|startswith|endswith)\b)|('[^']*'|"[^"]*"|\d+(?:\.\d+)?)|([<>=!]+)|(\b(?:and|or|not)\b)|(\(|\))|(\w+)/gi;
+        let match;
+        while ((match = tokenRegex.exec(filter)) !== null) {
+            const token = match[0];
+            if (match[1]) {
+                // OData operators
+                tokens.push({ type: "operator", value: token.toLowerCase() });
+            }
+            else if (match[2]) {
+                // Literal values (strings, numbers) - prioritized to avoid misclassification
+                tokens.push({ type: "literal", value: token });
+            }
+            else if (match[3]) {
+                // Comparison operators
+                tokens.push({ type: "operator", value: token });
+            }
+            else if (match[4]) {
+                // Logical operators
+                tokens.push({ type: "logical", value: token.toLowerCase() });
+            }
+            else if (match[5]) {
+                // Parentheses
+                tokens.push({ type: "paren", value: token });
+            }
+            else if (match[6]) {
+                // Property or function names
+                tokens.push({ type: "property", value: token });
+            }
+        }
+        return tokens;
+    }
+    /**
+     * Validates all filter tokens against allowed properties and operators
+     * @param tokens - Array of parsed filter tokens to validate
+     * @throws Error if any token contains invalid properties or operators
+     */
+    validateFilterTokens(tokens) {
+        for (const token of tokens) {
+            switch (token.type) {
+                case "property":
+                    // Check if it's a known OData function
+                    if (!ALLOWED_OPERATORS.has(token.value.toLowerCase()) &&
+                        !this.allowedProperties.has(token.value)) {
+                        throw new Error(`Invalid property in filter: ${token.value}. Allowed properties: ${Array.from(this.allowedProperties).join(", ")}`);
+                    }
+                    break;
+                case "operator":
+                    // Validate operator format (both symbols and OData operators)
+                    if (!/^[<>=!]+$/.test(token.value) &&
+                        !ALLOWED_OPERATORS.has(token.value.toLowerCase())) {
+                        throw new Error(`Invalid operator: ${token.value}`);
+                    }
+                    break;
+                case "logical":
+                    if (!["and", "or", "not"].includes(token.value)) {
+                        throw new Error(`Invalid logical operator: ${token.value}`);
+                    }
+                    break;
+            }
+        }
+    }
+    /**
+     * Converts validated OData filter tokens to CDS-compatible filter syntax
+     * @param tokens - Array of validated filter tokens
+     * @returns CDS filter expression string
+     */
+    convertToCdsFilter(tokens) {
+        const cdsTokens = [];
+        for (const token of tokens) {
+            if (token.type === "operator") {
+                // Convert OData operators to CDS operators
+                switch (token.value.toLowerCase()) {
+                    case "eq":
+                        cdsTokens.push("=");
+                        break;
+                    case "ne":
+                        cdsTokens.push("!=");
+                        break;
+                    case "gt":
+                        cdsTokens.push(">");
+                        break;
+                    case "ge":
+                        cdsTokens.push(">=");
+                        break;
+                    case "lt":
+                        cdsTokens.push("<");
+                        break;
+                    case "le":
+                        cdsTokens.push("<=");
+                        break;
+                    default:
+                        cdsTokens.push(token.value);
+                        break;
+                }
+            }
+            else {
+                cdsTokens.push(token.value);
+                continue;
+            }
+        }
+        return cdsTokens.join(" ");
+    }
+}
+exports.ODataQueryValidator = ODataQueryValidator;
+/**
+ * Specialized error class for OData query parameter validation failures
+ * Provides additional context about which parameter and value caused the error
+ */
+class ODataValidationError extends Error {
+    parameter;
+    value;
+    /**
+     * Creates a new OData validation error
+     * @param message - Error description
+     * @param parameter - Name of the parameter that failed validation
+     * @param value - The invalid value that caused the error
+     */
+    constructor(message, parameter, value) {
+        super(message);
+        this.parameter = parameter;
+        this.value = value;
+        this.name = "ODataValidationError";
+    }
+}
+exports.ODataValidationError = ODataValidationError;