@gavdi/cap-mcp 0.9.0 → 0.9.1

package/lib/annotations/constants.js

@@ -1,18 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_ALL_RESOURCE_OPTIONS = exports.MCP_ANNOTATION_PROPS = exports.MCP_ANNOTATION_KEY = void 0;
+/**
+ * MCP annotation constants and default configurations
+ * Defines the standard annotation keys and default values used throughout the plugin
+ */
+/**
+ * Base key used to identify MCP annotations in CDS definitions
+ * All MCP annotations must start with this prefix
+ */
 exports.MCP_ANNOTATION_KEY = "@mcp";
+/**
+ * Complete set of supported MCP annotation property names
+ * Maps logical names to their actual annotation keys used in CDS files
+ */
 exports.MCP_ANNOTATION_PROPS = {
-    // Standard annotations - required for all
+    /** Name identifier annotation - required for all MCP elements */
     MCP_NAME: "@mcp.name",
+    /** Description annotation - required for all MCP elements */
     MCP_DESCRIPTION: "@mcp.description",
-    // Resource annotations for MCP
+    /** Resource configuration annotation for CAP entities */
     MCP_RESOURCE: "@mcp.resource",
-    // Tool annotations for MCP
+    /** Tool configuration annotation for CAP functions/actions */
     MCP_TOOL: "@mcp.tool",
-    // Prompt annotations for MCP
+    /** Prompt templates annotation for CAP services */
     MCP_PROMPT: "@mcp.prompts",
 };
+/**
+ * Default set of all available OData query options for MCP resources
+ * Used when @mcp.resource is set to `true` to enable all capabilities
+ * Includes: $filter, $orderby, $top, $skip, $select
+ */
 exports.DEFAULT_ALL_RESOURCE_OPTIONS = new Set([
     "filter",
     "orderby",

package/lib/annotations/parser.js

@@ -5,6 +5,12 @@ const logger_1 = require("../logger");
 const structures_1 = require("./structures");
 const utils_1 = require("./utils");
 const constants_1 = require("./constants");
+/**
+ * Parses model definitions to extract MCP annotations and return them as a map of annotated entries
+ * @param model - The CSN model containing definitions to parse
+ * @returns A map of target names to their corresponding MCP annotation entries
+ * @throws Error if model lacks valid definitions
+ */
 function parseDefinitions(model) {
     if (!model.definitions) {
         logger_1.LOGGER.error("Invalid model loaded", model);
@@ -50,6 +56,11 @@ function parseDefinitions(model) {
     }
     return result;
 }
+/**
+ * Parses MCP annotations from a definition object
+ * @param definition - The definition object to parse annotations from
+ * @returns Partial annotation structure or undefined if no MCP annotations found
+ */
 function parseAnnotations(definition) {
     if (!(0, utils_1.containsMcpAnnotation)(definition))
         return undefined;
@@ -82,6 +93,14 @@ function parseAnnotations(definition) {
     }
     return annotations;
 }
+/**
+ * Constructs a resource annotation from parsed annotation data
+ * @param serviceName - Name of the service containing the resource
+ * @param target - Target entity name
+ * @param annotations - Parsed annotation structure
+ * @param definition - CSN definition object
+ * @returns Resource annotation or undefined if invalid
+ */
 function constructResourceAnnotation(serviceName, target, annotations, definition) {
     if (!(0, utils_1.isValidResourceAnnotation)(annotations))
         return undefined;
@@ -89,26 +108,45 @@ function constructResourceAnnotation(serviceName, target, annotations, definitio
     const { properties, resourceKeys } = (0, utils_1.parseResourceElements)(definition);
     return new structures_1.McpResourceAnnotation(annotations.name, annotations.description, target, serviceName, functionalities, properties, resourceKeys);
 }
+/**
+ * Constructs a tool annotation from parsed annotation data
+ * @param serviceName - Name of the service containing the tool
+ * @param target - Target operation name
+ * @param annotations - Parsed annotation structure
+ * @param entityKey - Optional entity key for bound operations
+ * @param keyParams - Optional key parameters for bound operations
+ * @returns Tool annotation or undefined if invalid
+ */
 function constructToolAnnotation(serviceName, target, annotations, entityKey, keyParams) {
     if (!(0, utils_1.isValidToolAnnotation)(annotations))
         return undefined;
     const { parameters, operationKind } = (0, utils_1.parseOperationElements)(annotations);
     return new structures_1.McpToolAnnotation(annotations.name, annotations.description, target, serviceName, parameters, entityKey, operationKind, keyParams);
 }
+/**
+ * Constructs a prompt annotation from parsed annotation data
+ * @param serviceName - Name of the service containing the prompts
+ * @param annotations - Parsed annotation structure
+ * @returns Prompt annotation or undefined if invalid
+ */
 function constructPromptAnnotation(serviceName, annotations) {
     if (!(0, utils_1.isValidPromptsAnnotation)(annotations))
         return undefined;
     return new structures_1.McpPromptAnnotation(annotations.name, annotations.description, serviceName, annotations.prompts);
 }
 /**
- * Parses the bound operations found on the entity definition if any.
- * This function mutates the passed result reference object.
+ * Parses bound operations (actions/functions) attached to an entity definition
+ * Extracts MCP tool annotations from entity-level operations and adds them to the result map
+ * @param serviceName - Name of the service containing the entity
+ * @param entityKey - Name of the entity that owns these bound operations
+ * @param definition - CSN entity definition containing bound operations
+ * @param resultRef - Map to store parsed annotations (mutated by this function)
  */
 function parseBoundOperations(serviceName, entityKey, definition, resultRef) {
     if (definition.kind !== "entity")
         return;
     const boundOperations = definition
-        .actions; // Necessary due to missing type reference
+        .actions; // NOTE: Necessary due to missing type reference in cds-types
     if (!boundOperations)
         return;
     const keyParams = (0, utils_1.parseEntityKeys)(definition);

package/lib/annotations/structures.js

@@ -1,57 +1,136 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpPromptAnnotation = exports.McpToolAnnotation = exports.McpResourceAnnotation = exports.McpAnnotation = void 0;
+/**
+ * Base class for all MCP annotations that provides common properties
+ * and functionality shared across different annotation types
+ */
 class McpAnnotation {
+    /** The name identifier for this annotation */
     _name;
+    /** AI agent readable description of what this annotation represents */
     _description;
+    /** The target entity, function, or service element this annotation applies to */
     _target;
+    /** The name of the CAP service this annotation belongs to */
     _serviceName;
+    /**
+     * Creates a new MCP annotation instance
+     * @param name - Unique identifier for this annotation
+     * @param description - Human-readable description
+     * @param target - The target element this annotation applies to
+     * @param serviceName - Name of the associated CAP service
+     */
     constructor(name, description, target, serviceName) {
         this._name = name;
         this._description = description;
         this._target = target;
         this._serviceName = serviceName;
     }
+    /**
+     * Gets the unique name identifier for this annotation
+     * @returns The annotation name
+     */
     get name() {
         return this._name;
     }
+    /**
+     * Gets the human-readable description of this annotation
+     * @returns The annotation description
+     */
     get description() {
         return this._description;
     }
+    /**
+     * Gets the target element this annotation applies to
+     * @returns The target identifier
+     */
     get target() {
         return this._target;
     }
+    /**
+     * Gets the name of the CAP service this annotation belongs to
+     * @returns The service name
+     */
     get serviceName() {
         return this._serviceName;
     }
 }
 exports.McpAnnotation = McpAnnotation;
+/**
+ * Annotation class for MCP resources that can be queried with OData parameters
+ * Extends the base annotation with resource-specific configuration
+ */
 class McpResourceAnnotation extends McpAnnotation {
+    /** Set of OData query functionalities enabled for this resource */
     _functionalities;
+    /** Map of property names to their CDS types for validation */
     _properties;
+    /** Map of resource key fields to their types */
     _resourceKeys;
+    /**
+     * Creates a new MCP resource annotation
+     * @param name - Unique identifier for this resource
+     * @param description - Human-readable description
+     * @param target - The CAP entity this resource represents
+     * @param serviceName - Name of the associated CAP service
+     * @param functionalities - Set of enabled OData query options (filter, top, skip, etc.)
+     * @param properties - Map of entity properties to their CDS types
+     * @param resourceKeys - Map of key fields to their types
+     */
     constructor(name, description, target, serviceName, functionalities, properties, resourceKeys) {
         super(name, description, target, serviceName);
         this._functionalities = functionalities;
         this._properties = properties;
         this._resourceKeys = resourceKeys;
     }
+    /**
+     * Gets the set of enabled OData query functionalities
+     * @returns Set of available query options like 'filter', 'top', 'skip'
+     */
     get functionalities() {
         return this._functionalities;
     }
+    /**
+     * Gets the map of entity properties to their CDS types
+     * @returns Map of property names to type strings
+     */
     get properties() {
         return this._properties;
     }
+    /**
+     * Gets the map of resource key fields to their types
+     * @returns Map of key field names to type strings
+     */
     get resourceKeys() {
         return this._resourceKeys;
     }
 }
 exports.McpResourceAnnotation = McpResourceAnnotation;
+/**
+ * Annotation class for MCP tools that represent executable CAP functions or actions
+ * Can be either bound (entity-level) or unbound (service-level) operations
+ */
 class McpToolAnnotation extends McpAnnotation {
+    /** Map of function parameters to their CDS types */
     _parameters;
+    /** Entity key field name for bound operations */
     _entityKey;
+    /** Type of operation: 'function' or 'action' */
     _operationKind;
+    /** Map of key field names to their types for bound operations */
     _keyTypeMap;
+    /**
+     * Creates a new MCP tool annotation
+     * @param name - Unique identifier for this tool
+     * @param description - Human-readable description
+     * @param operation - The CAP function or action name
+     * @param serviceName - Name of the associated CAP service
+     * @param parameters - Optional map of function parameters to their types
+     * @param entityKey - Optional entity key field for bound operations
+     * @param operationKind - Optional operation type ('function' or 'action')
+     * @param keyTypeMap - Optional map of key fields to types for bound operations
+     */
     constructor(name, description, operation, serviceName, parameters, entityKey, operationKind, keyTypeMap) {
         super(name, description, operation, serviceName);
         this._parameters = parameters;
@@ -59,26 +138,58 @@ class McpToolAnnotation extends McpAnnotation {
         this._operationKind = operationKind;
         this._keyTypeMap = keyTypeMap;
     }
+    /**
+     * Gets the map of function parameters to their CDS types
+     * @returns Map of parameter names to type strings, or undefined if no parameters
+     */
     get parameters() {
         return this._parameters;
     }
+    /**
+     * Gets the entity key field name for bound operations
+     * @returns Entity key field name, or undefined for unbound operations
+     */
     get entityKey() {
         return this._entityKey;
     }
+    /**
+     * Gets the operation kind (function or action)
+     * @returns Operation type string, or undefined if not specified
+     */
     get operationKind() {
         return this._operationKind;
     }
+    /**
+     * Gets the map of key field names to their types for bound operations
+     * @returns Map of key fields to types, or undefined for unbound operations
+     */
     get keyTypeMap() {
         return this._keyTypeMap;
     }
 }
 exports.McpToolAnnotation = McpToolAnnotation;
+/**
+ * Annotation class for MCP prompts that define reusable prompt templates
+ * Applied at the service level to provide prompt templates with variable substitution
+ */
 class McpPromptAnnotation extends McpAnnotation {
+    /** Array of prompt template definitions */
     _prompts;
+    /**
+     * Creates a new MCP prompt annotation
+     * @param name - Unique identifier for this prompt collection
+     * @param description - Human-readable description
+     * @param serviceName - Name of the associated CAP service
+     * @param prompts - Array of prompt template definitions
+     */
     constructor(name, description, serviceName, prompts) {
         super(name, description, serviceName, serviceName);
         this._prompts = prompts;
     }
+    /**
+     * Gets the array of prompt template definitions
+     * @returns Array of prompt templates with their inputs and templates
+     */
     get prompts() {
         return this._prompts;
     }

package/lib/annotations/utils.js

@@ -12,6 +12,11 @@ exports.parseOperationElements = parseOperationElements;
 exports.parseEntityKeys = parseEntityKeys;
 const constants_1 = require("./constants");
 const logger_1 = require("../logger");
+/**
+ * Splits a definition name into service name and target
+ * @param definition - The definition name to split
+ * @returns Object containing serviceName and target
+ */
 function splitDefinitionName(definition) {
     const splitted = definition.split(".");
     return {
@@ -19,6 +24,11 @@ function splitDefinitionName(definition) {
         target: splitted[1],
     };
 }
+/**
+ * Checks if a definition contains any MCP annotations
+ * @param definition - The definition to check
+ * @returns True if MCP annotations are found, false otherwise
+ */
 function containsMcpAnnotation(definition) {
     for (const key of Object.keys(definition)) {
         if (!key.includes(constants_1.MCP_ANNOTATION_KEY))
@@ -27,6 +37,12 @@ function containsMcpAnnotation(definition) {
     }
     return false;
 }
+/**
+ * Validates that required MCP annotations are present and valid
+ * @param annotations - The annotation structure to validate
+ * @returns True if valid, throws error if invalid
+ * @throws Error if required annotations are missing
+ */
 function containsRequiredAnnotations(annotations) {
     if (annotations.definition?.kind === "service")
         return true;
@@ -38,6 +54,12 @@ function containsRequiredAnnotations(annotations) {
     }
     return true;
 }
+/**
+ * Validates a resource annotation structure
+ * @param annotations - The annotation structure to validate
+ * @returns True if valid, throws error if invalid
+ * @throws Error if resource annotation is invalid
+ */
 function isValidResourceAnnotation(annotations) {
     if (!annotations?.resource) {
         throw new Error(`Invalid annotation '${annotations.definition?.target}' - Missing required flag 'resource'`);
@@ -51,12 +73,24 @@ function isValidResourceAnnotation(annotations) {
     }
     return true;
 }
+/**
+ * Validates a tool annotation structure
+ * @param annotations - The annotation structure to validate
+ * @returns True if valid, throws error if invalid
+ * @throws Error if tool annotation is invalid
+ */
 function isValidToolAnnotation(annotations) {
     if (!annotations?.tool) {
         throw new Error(`Invalid annotation '${annotations.definition?.target}' - Missing required flag 'tool'`);
     }
     return true;
 }
+/**
+ * Validates a prompts annotation structure
+ * @param annotations - The annotation structure to validate
+ * @returns True if valid, throws error if invalid
+ * @throws Error if prompts annotation is invalid
+ */
 function isValidPromptsAnnotation(annotations) {
     if (!annotations?.prompts) {
         throw new Error(`Invalid annotation '${annotations.definition?.target}' - Missing prompts annotations`);
@@ -87,11 +121,21 @@ function isValidPromptsAnnotation(annotations) {
     }
     return true;
 }
+/**
+ * Determines resource options from annotation structure
+ * @param annotations - The annotation structure to process
+ * @returns Set of resource options, defaults to all options if not specified
+ */
 function determineResourceOptions(annotations) {
     if (!Array.isArray(annotations.resource))
         return constants_1.DEFAULT_ALL_RESOURCE_OPTIONS;
     return new Set(annotations.resource);
 }
+/**
+ * Parses resource elements from a definition to extract properties and keys
+ * @param definition - The definition to parse
+ * @returns Object containing properties and resource keys maps
+ */
 function parseResourceElements(definition) {
     const properties = new Map();
     const resourceKeys = new Map();
@@ -109,6 +153,11 @@ function parseResourceElements(definition) {
         resourceKeys,
     };
 }
+/**
+ * Parses operation elements from annotation structure
+ * @param annotations - The annotation structure to parse
+ * @returns Object containing parameters and operation kind
+ */
 function parseOperationElements(annotations) {
     let parameters;
     const params = annotations.definition["params"];
@@ -123,6 +172,12 @@ function parseOperationElements(annotations) {
         operationKind: annotations.definition.kind,
     };
 }
+/**
+ * Parses entity keys from a definition
+ * @param definition - The definition to parse keys from
+ * @returns Map of key names to their types
+ * @throws Error if invalid key type is found
+ */
 function parseEntityKeys(definition) {
     const result = new Map();
     for (const [k, v] of Object.entries(definition.elements)) {

package/lib/config/env-sanitizer.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSafeEnvVar = getSafeEnvVar;
+exports.isTestEnvironment = isTestEnvironment;
+const logger_1 = require("../logger");
+/**
+ * Dangerous characters that could be used for injection attacks
+ */
+const DANGEROUS_CHARS = /[;&|`$()<>!]/g;
+/**
+ * Validation patterns for specific environment variables
+ */
+const VALIDATION_PATTERNS = {
+    npm_package_name: /^[a-zA-Z0-9\-_@/\.]+$/,
+    npm_package_version: /^\d+\.\d+\.\d+(-[a-zA-Z0-9\-\.]+)?(\+[a-zA-Z0-9\-\.]+)?$/,
+    NODE_ENV: /^(development|production|test)$/,
+};
+/**
+ * Sanitizes environment variable value by removing dangerous characters
+ * @param value - Raw environment variable value
+ * @param key - Environment variable key for logging
+ * @returns Sanitized value with dangerous characters removed
+ */
+function sanitizeValue(value, key) {
+    const originalValue = value;
+    const sanitized = value.replace(DANGEROUS_CHARS, "").trim();
+    if (sanitized !== originalValue) {
+        logger_1.LOGGER.warn(`Environment variable '${key}' contained potentially dangerous characters and was sanitized`);
+    }
+    return sanitized;
+}
+/**
+ * Validates environment variable value against expected pattern
+ * @param value - Sanitized environment variable value
+ * @param key - Environment variable key
+ * @returns True if valid, false otherwise
+ */
+function validateValue(value, key) {
+    const pattern = VALIDATION_PATTERNS[key];
+    if (!pattern)
+        return true; // No validation pattern defined
+    const isValid = pattern.test(value);
+    if (!isValid) {
+        logger_1.LOGGER.warn(`Environment variable '${key}' value '${value}' does not match expected pattern`);
+    }
+    return isValid;
+}
+/**
+ * Safely retrieves and sanitizes an environment variable
+ * @param key - Environment variable key
+ * @param defaultValue - Default value if environment variable is not set or invalid
+ * @returns Sanitized environment variable value or default
+ */
+function getSafeEnvVar(key, defaultValue = "") {
+    const rawValue = process.env[key];
+    // Return default if not set or empty
+    if (!rawValue || rawValue.trim().length === 0) {
+        return defaultValue;
+    }
+    // Sanitize the value
+    const sanitized = sanitizeValue(rawValue, key);
+    // Validate if pattern exists
+    if (key in VALIDATION_PATTERNS) {
+        const isValid = validateValue(sanitized, key);
+        if (!isValid) {
+            logger_1.LOGGER.warn(`Using default value for invalid environment variable '${key}'`);
+            return defaultValue;
+        }
+    }
+    return sanitized;
+}
+/**
+ * Checks if current environment is test
+ * @returns True if NODE_ENV is 'test'
+ */
+function isTestEnvironment() {
+    return getSafeEnvVar("NODE_ENV", "development") === "test";
+}

package/lib/config/json-parser.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonParseError = exports.JsonParseErrorType = void 0;
+exports.safeJsonParse = safeJsonParse;
+exports.parseCAPConfiguration = parseCAPConfiguration;
+exports.createSafeErrorMessage = createSafeErrorMessage;
+const zod_1 = require("zod");
+const logger_1 = require("../logger");
+/**
+ * Configuration schema for validation
+ */
+const CAPConfigurationSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    version: zod_1.z.string(),
+    capabilities: zod_1.z.object({
+        tools: zod_1.z.object({
+            listChanged: zod_1.z.boolean().optional(),
+        }),
+        resources: zod_1.z.object({
+            listChanged: zod_1.z.boolean().optional(),
+            subscribe: zod_1.z.boolean().optional(),
+        }),
+        prompts: zod_1.z.object({
+            listChanged: zod_1.z.boolean().optional(),
+        }),
+    }),
+});
+/**
+ * Error types for JSON parsing failures
+ */
+var JsonParseErrorType;
+(function (JsonParseErrorType) {
+    JsonParseErrorType["INVALID_INPUT"] = "INVALID_INPUT";
+    JsonParseErrorType["PARSE_ERROR"] = "PARSE_ERROR";
+    JsonParseErrorType["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+})(JsonParseErrorType || (exports.JsonParseErrorType = JsonParseErrorType = {}));
+/**
+ * Custom error class for JSON parsing failures
+ */
+class JsonParseError extends Error {
+    type;
+    details;
+    constructor(type, message, details) {
+        super(message);
+        this.type = type;
+        this.details = details;
+        this.name = "JsonParseError";
+    }
+}
+exports.JsonParseError = JsonParseError;
+/**
+ * Validates basic JSON structure without parsing
+ * @param input - JSON string to validate
+ * @returns True if basic structure is valid
+ */
+function hasValidJsonStructure(input) {
+    // Check for balanced braces and brackets
+    let braceCount = 0;
+    let bracketCount = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < input.length; i++) {
+        const char = input[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        switch (char) {
+            case "{":
+                braceCount++;
+                break;
+            case "}":
+                braceCount--;
+                break;
+            case "[":
+                bracketCount++;
+                break;
+            case "]":
+                bracketCount--;
+                break;
+        }
+        // Early detection of imbalanced brackets
+        if (braceCount < 0 || bracketCount < 0) {
+            return false;
+        }
+    }
+    return braceCount === 0 && bracketCount === 0 && !inString;
+}
+/**
+ * Safely parses JSON with comprehensive security checks
+ * @param input - JSON string to parse
+ * @param schema - Zod schema for validation
+ * @returns Parsed and validated object or null if parsing fails
+ */
+function safeJsonParse(input, schema) {
+    try {
+        // Input validation
+        if (typeof input !== "string") {
+            throw new JsonParseError(JsonParseErrorType.INVALID_INPUT, "Input must be a string", `Received: ${typeof input}`);
+        }
+        // Trim whitespace
+        const trimmed = input.trim();
+        if (trimmed.length === 0) {
+            throw new JsonParseError(JsonParseErrorType.INVALID_INPUT, "Input is empty or contains only whitespace");
+        }
+        // Basic structure validation
+        if (!hasValidJsonStructure(trimmed)) {
+            throw new JsonParseError(JsonParseErrorType.PARSE_ERROR, "Invalid JSON structure detected");
+        }
+        // Parse JSON
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (error) {
+            throw new JsonParseError(JsonParseErrorType.PARSE_ERROR, "JSON parsing failed", error instanceof Error ? error.message : "Unknown parse error");
+        }
+        // Schema validation
+        const validationResult = schema.safeParse(parsed);
+        if (!validationResult.success) {
+            throw new JsonParseError(JsonParseErrorType.VALIDATION_ERROR, "JSON does not match expected schema", validationResult.error.message);
+        }
+        return validationResult.data;
+    }
+    catch (error) {
+        if (error instanceof JsonParseError) {
+            // Log detailed error for debugging (without exposing to user)
+            logger_1.LOGGER.warn(`Safe JSON parsing failed: ${error.type}`, {
+                message: error.message,
+                details: error.details,
+            });
+        }
+        else {
+            // Unexpected error
+            logger_1.LOGGER.warn("Unexpected error during JSON parsing", error);
+        }
+        return null;
+    }
+}
+/**
+ * Safely parses CAP configuration JSON
+ * @param input - JSON string containing CAP configuration
+ * @returns Parsed CAPConfiguration or null if parsing fails
+ */
+function parseCAPConfiguration(input) {
+    return safeJsonParse(input, CAPConfigurationSchema);
+}
+/**
+ * Creates a generic error message for user-facing errors
+ * @param context - Context where the error occurred
+ * @returns Generic error message that doesn't expose sensitive information
+ */
+function createSafeErrorMessage(context) {
+    return `Configuration parsing failed in ${context}. Please check the configuration format.`;
+}