@gavdi/cap-mcp 1.3.1 → 1.4.0

package/README.md

@@ -24,6 +24,8 @@ By integrating MCP with your CAP applications, you unlock:
 
 ## 🚀 Quick Setup
 
+> Want to read the full documentation? [Find it here](https://gavdilabs.github.io/cap-mcp-plugin/#/)
+
 ### Prerequisites
 
 - **Node.js**: Version 18 or higher
@@ -68,7 +70,7 @@ service CatalogService {
   @mcp: {
     name: 'books',
     description: 'Book catalog with search and filtering',
-    resource: ['filter', 'orderby', 'select', 'top', 'skip']
+    resource: ['filter', 'orderby', 'select', 'top', 'skip', 'expand']
   }
   entity Books as projection on my.Books;
 
@@ -115,6 +117,7 @@ This plugin transforms your annotated CAP services into a fully functional MCP s
 - **📊 Resources**: Expose CAP entities as MCP resources with OData v4 query capabilities
 - **🔧 Tools**: Convert CAP functions and actions into executable MCP tools
 - **🧩 Entity Wrappers (optional)**: Expose CAP entities as tools (`query`, `get`, and optionally `create`, `update`) for LLM tool use while keeping resources intact
+- **🔗 Deep Insert**: Create parent and child entities in a single operation with `@mcp.deepInsert` annotation
 - **💡 Prompts**: Define reusable prompt templates for AI interactions
 - **⚡ Elicitation**: Request user confirmation or input parameters before tool execution
 - **🔄 Auto-generation**: Automatically creates MCP server endpoints based on annotations
@@ -148,7 +151,8 @@ service CatalogService {
       'orderby',
       'select',
       'skip',
-      'top'
+      'top',
+      'expand'
     ]
   }
   entity Books as projection on my.Books;
@@ -172,7 +176,7 @@ service CatalogService {
 ```
 
 **Generated MCP Resource Capabilities:**
-- **OData v4 Query Support**: `$filter`, `$orderby`, `$top`, `$skip`, `$select`
+- **OData v4 Query Support**: `$filter`, `$orderby`, `$top`, `$skip`, `$select`, `$expand`
 - **Natural Language Queries**: "Find books by Stephen King with stock > 20"
 - **Dynamic Filtering**: Complex filter expressions using OData syntax
 - **Flexible Selection**: Choose specific fields and sort orders

package/cds-plugin.js

@@ -5,7 +5,7 @@ const McpBuild = require("./lib/config/build");
 // Build tasks
 McpBuild.registerBuildTask();
 
-const plugin = new McpPlugin();
+const plugin = McpPlugin.getInstance();
 
 // Plugin hooks event registration
 cds.on("bootstrap", async (app) => {

package/lib/annotations/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MCP_OMIT_PROP_KEY = exports.MCP_HINT_ELEMENT = exports.DEFAULT_ALL_RESOURCE_OPTIONS = exports.MCP_ANNOTATION_MAPPING = exports.MCP_ANNOTATION_KEY = void 0;
+exports.MCP_DEEP_INSERT_KEY = exports.MCP_OMIT_PROP_KEY = exports.MCP_HINT_ELEMENT = exports.DEFAULT_ALL_RESOURCE_OPTIONS = exports.MCP_ANNOTATION_MAPPING = exports.MCP_ANNOTATION_KEY = void 0;
 /**
  * MCP annotation constants and default configurations
  * Defines the standard annotation keys and default values used throughout the plugin
@@ -29,6 +29,7 @@ exports.MCP_ANNOTATION_MAPPING = new Map([
     ["@mcp.wrap.hint.update", "wrap.hint.update"],
     ["@mcp.wrap.hint.delete", "wrap.hint.delete"],
     ["@mcp.elicit", "elicit"],
+    ["@mcp.deepInsert", "deepInsert"],
     ["@requires", "requires"],
     ["@restrict", "restrict"],
 ]);
@@ -43,6 +44,7 @@ exports.DEFAULT_ALL_RESOURCE_OPTIONS = new Set([
     "top",
     "skip",
     "select",
+    "expand",
 ]);
 /**
  * Hint key for annotations made on specific properties/elements
@@ -52,3 +54,7 @@ exports.MCP_HINT_ELEMENT = "@mcp.hint";
  * MCP omit property annotation key
  */
 exports.MCP_OMIT_PROP_KEY = "@mcp.omit";
+/**
+ * MCP deep insert annotation key for element-level deep insert references
+ */
+exports.MCP_DEEP_INSERT_KEY = "@mcp.deepInsert";

package/lib/annotations/parser.js

@@ -138,7 +138,35 @@ function constructResourceAnnotation(serviceName, target, annotations, definitio
         .map(([k, _]) => k));
     const { properties, resourceKeys, propertyHints } = (0, utils_1.parseResourceElements)(definition, model);
     const restrictions = (0, utils_1.parseCdsRestrictions)(annotations.restrict, annotations.requires);
-    return new structures_1.McpResourceAnnotation(annotations.name, annotations.description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, annotations.wrap, restrictions, computedFields, propertyHints, omittedFields);
+    const deepInsertRefs = (0, utils_1.parseDeepInsertRefs)(definition);
+    // Build association safe columns map
+    const associationSafeColumns = new Map();
+    const entityDef = model.definitions?.[entityTarget];
+    if (entityDef?.elements) {
+        for (const [propName, propDef] of Object.entries(entityDef.elements)) {
+            const cdsType = String(propDef.type || "");
+            if (!cdsType.toLowerCase().includes("association"))
+                continue;
+            // Get target entity from the association definition
+            const assocTarget = propDef.target;
+            if (!assocTarget)
+                continue;
+            const targetDef = model.definitions?.[assocTarget];
+            if (!targetDef?.elements)
+                continue;
+            // Find omitted fields on the target entity
+            const targetOmitted = new Set(Object.entries(targetDef.elements)
+                .filter(([_, v]) => v[constants_1.MCP_OMIT_PROP_KEY])
+                .map(([k]) => k));
+            // If target has omitted fields, compute safe columns
+            if (targetOmitted.size > 0) {
+                const safeColumns = Object.keys(targetDef.elements).filter((k) => !targetOmitted.has(k));
+                associationSafeColumns.set(propName, safeColumns);
+            }
+            // If no omitted fields, don't add to map (will use '*' as fallback)
+        }
+    }
+    return new structures_1.McpResourceAnnotation(annotations.name, annotations.description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, annotations.wrap, restrictions, computedFields, propertyHints, omittedFields, deepInsertRefs, associationSafeColumns);
 }
 /**
  * Constructs a tool annotation from parsed annotation data

package/lib/annotations/structures.js

@@ -98,6 +98,10 @@ class McpResourceAnnotation extends McpAnnotation {
     _computedFields;
     /** List of omitted fields */
     _omittedFields;
+    /** Map of association property names to target entity names for deep insert */
+    _deepInsertRefs;
+    /** Map of association name → target entity's safe columns (excluding omitted) */
+    _associationSafeColumns;
     /**
      * Creates a new MCP resource annotation
      * @param name - Unique identifier for this resource
@@ -113,8 +117,10 @@ class McpResourceAnnotation extends McpAnnotation {
      * @param computedFields - Optional set of fields that are computed and should be ignored in create scenarios
      * @param propertyHints - Optional map of hints for specific properties on resource
      * @param omittedFields - Optional set of fields that should be omitted from MCP entity
+     * @param deepInsertRefs - Optional map of association property names to target entity names for deep insert
+     * @param associationSafeColumns - Optional map of association names to their safe columns (pre-computed)
      */
-    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, wrap, restrictions, computedFields, propertyHints, omittedFields) {
+    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, wrap, restrictions, computedFields, propertyHints, omittedFields, deepInsertRefs, associationSafeColumns) {
         super(name, description, target, serviceName, restrictions ?? [], propertyHints ?? new Map());
         this._functionalities = functionalities;
         this._properties = properties;
@@ -123,6 +129,8 @@ class McpResourceAnnotation extends McpAnnotation {
         this._foreignKeys = foreignKeys;
         this._computedFields = computedFields;
         this._omittedFields = omittedFields;
+        this._deepInsertRefs = deepInsertRefs ?? new Map();
+        this._associationSafeColumns = associationSafeColumns;
     }
     /**
      * Gets the set of enabled OData query functionalities
@@ -170,6 +178,31 @@ class McpResourceAnnotation extends McpAnnotation {
     get omittedFields() {
         return this._omittedFields;
     }
+    /**
+     * Gets the map of association property names to target entity names for deep insert
+     * @returns Map of association names to entity names for deep insert schema references
+     */
+    get deepInsertRefs() {
+        return this._deepInsertRefs;
+    }
+    /**
+     * Gets the list of safe (non-omitted) columns for the main entity.
+     * Returns ['*'] if no fields are omitted, otherwise returns explicit column list.
+     */
+    get safeColumns() {
+        if (!this._omittedFields || this._omittedFields.size === 0) {
+            return ["*"]; // No omitted fields, safe to use star
+        }
+        return Array.from(this._properties.keys()).filter((k) => !this._omittedFields?.has(k));
+    }
+    /**
+     * Gets safe columns for an association target, if available.
+     * Returns undefined if the association has no omitted fields (use '*' as fallback).
+     * @param assocName - Name of the association property
+     */
+    getAssociationSafeColumns(assocName) {
+        return this._associationSafeColumns?.get(assocName);
+    }
 }
 exports.McpResourceAnnotation = McpResourceAnnotation;
 /**

package/lib/annotations/utils.js

@@ -12,6 +12,7 @@ exports.parseResourceElements = parseResourceElements;
 exports.parseOperationElements = parseOperationElements;
 exports.parseEntityKeys = parseEntityKeys;
 exports.parseCdsRestrictions = parseCdsRestrictions;
+exports.parseDeepInsertRefs = parseDeepInsertRefs;
 const constants_1 = require("./constants");
 const logger_1 = require("../logger");
 /**
@@ -345,3 +346,29 @@ function translateOperationRestriction(restrictionType) {
             return [restrictionType];
     }
 }
+/**
+ * Parses @mcp.deepInsert annotations from entity elements
+ * @param definition - The entity definition to parse
+ * @returns Map of association property names to target entity names for deep insert
+ */
+function parseDeepInsertRefs(definition) {
+    const deepInsertRefs = new Map();
+    if (!definition?.elements)
+        return deepInsertRefs;
+    for (const [propName, element] of Object.entries(definition.elements)) {
+        // Check if element has @mcp.deepInsert annotation (boolean or truthy)
+        const hasDeepInsert = element[constants_1.MCP_DEEP_INSERT_KEY];
+        if (hasDeepInsert) {
+            // Infer target from association/composition definition
+            const targetEntity = element.target;
+            if (targetEntity) {
+                deepInsertRefs.set(propName, targetEntity);
+                logger_1.LOGGER.debug(`Found @mcp.deepInsert on ${propName} -> inferred target: ${targetEntity}`);
+            }
+            else {
+                logger_1.LOGGER.warn(`@mcp.deepInsert on ${propName} but no target entity found`);
+            }
+        }
+    }
+    return deepInsertRefs;
+}

package/lib/mcp/entity-tools.js

@@ -211,6 +211,10 @@ function registerQueryTool(resAnno, server, authEnabled) {
             .optional()
             .transform((val) => (val && val.length > 0 ? val : undefined)),
         explain: zod_1.z.boolean().optional(),
+        expand: zod_1.z
+            .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())])
+            .optional()
+            .describe('Expand associations: "*" for all, or array of association names'),
     })
         .strict();
     const inputSchema = {
@@ -223,6 +227,7 @@ function registerQueryTool(resAnno, server, authEnabled) {
         return: inputZod.shape.return,
         aggregate: inputZod.shape.aggregate,
         explain: inputZod.shape.explain,
+        expand: inputZod.shape.expand,
     };
     const hint = constructHintMessage(resAnno, "query");
     const desc = `Resource description: ${resAnno.description}. ${buildEnhancedQueryDescription(resAnno)} CRITICAL: Use foreign key fields (e.g., author_ID) for associations - association names (e.g., author) won't work in filters.` +
@@ -348,8 +353,19 @@ function registerCreateTool(resAnno, server, authEnabled) {
     for (const [propName, cdsType] of resAnno.properties.entries()) {
         const isAssociation = String(cdsType).toLowerCase().includes("association");
         const isComputed = resAnno.computedFields?.has(propName);
-        if (isAssociation || isComputed) {
-            // Association keys are supplied directly from model loading as of v1.1.2
+        // Check if this association is marked for deep insert
+        if (isAssociation) {
+            if (resAnno.deepInsertRefs.has(propName)) {
+                // This association has @mcp.deepInsert annotation
+                const targetEntityName = resAnno.deepInsertRefs.get(propName);
+                inputSchema[propName] = (0, utils_2.buildDeepInsertZodType)(targetEntityName)
+                    .optional()
+                    .describe(`Deep insert array for ${propName}. ${resAnno.propertyHints.get(propName) ?? ""}`);
+            }
+            // Skip regular associations (no deep insert)
+            continue;
+        }
+        if (isComputed) {
             continue;
         }
         inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType, propName, `${resAnno.serviceName}.${resAnno.target}`)
@@ -377,6 +393,15 @@ function registerCreateTool(resAnno, server, authEnabled) {
                 .toLowerCase()
                 .includes("association");
             if (isAssociation) {
+                // Check if this association is marked for deep insert
+                if (resAnno.deepInsertRefs.has(propName)) {
+                    // Pass through the nested array for deep insert
+                    if (args[propName] !== undefined && Array.isArray(args[propName])) {
+                        data[propName] = args[propName];
+                    }
+                    continue;
+                }
+                // Regular association - use foreign key
                 const fkName = `${propName}_ID`;
                 if (args[fkName] !== undefined) {
                     const val = args[fkName];
@@ -438,8 +463,19 @@ function registerUpdateTool(resAnno, server, authEnabled) {
             continue;
         const isComputed = resAnno.computedFields?.has(propName);
         const isAssociation = String(cdsType).toLowerCase().includes("association");
-        if (isAssociation || isComputed) {
-            // Association keys are supplied directly from model loading as of v1.1.2
+        if (isComputed) {
+            continue;
+        }
+        // Check if this association is marked for deep insert
+        if (isAssociation) {
+            if (resAnno.deepInsertRefs.has(propName)) {
+                // This association has @mcp.deepInsert annotation
+                const targetEntityName = resAnno.deepInsertRefs.get(propName);
+                inputSchema[propName] = (0, utils_2.buildDeepInsertZodType)(targetEntityName)
+                    .optional()
+                    .describe(`Deep update array for ${propName}. ${resAnno.propertyHints.get(propName) ?? ""}`);
+            }
+            // Skip regular associations (no deep insert)
             continue;
         }
         inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType, propName, `${resAnno.serviceName}.${resAnno.target}`)
@@ -480,6 +516,15 @@ function registerUpdateTool(resAnno, server, authEnabled) {
                 .toLowerCase()
                 .includes("association");
             if (isAssociation) {
+                // Check if this association is marked for deep insert
+                if (resAnno.deepInsertRefs.has(propName)) {
+                    // Pass through the nested array for deep update
+                    if (args[propName] !== undefined && Array.isArray(args[propName])) {
+                        updates[propName] = args[propName];
+                    }
+                    continue;
+                }
+                // Regular association - use foreign key
                 const fkName = `${propName}_ID`;
                 if (args[fkName] !== undefined) {
                     const val = args[fkName];
@@ -609,7 +654,49 @@ function buildQuery(CDS, args, resAnno, propKeys) {
     let qy = SELECT.from(resAnno.target).limit(limitTop, limitSkip);
     if ((propKeys?.length ?? 0) === 0)
         return qy;
-    if (args.select?.length) {
+    // Handle expand - must be processed before select to build proper columns
+    if (args.expand) {
+        // Detect available associations (raw names, NOT _ID suffixed)
+        const assocNames = Array.from(resAnno.properties.entries())
+            .filter(([, cdsType]) => String(cdsType).toLowerCase().includes("association"))
+            .map(([name]) => name);
+        // Normalize expand to array (handle both string and array input)
+        const expandInput = Array.isArray(args.expand)
+            ? args.expand
+            : [args.expand];
+        // Determine which associations to expand
+        const expandList = expandInput.includes("*") || expandInput[0] === "*"
+            ? assocNames
+            : expandInput.filter((e) => assocNames.includes(e));
+        // Build columns array with expand structures
+        if (expandList.length > 0) {
+            const expandColumns = expandList.map((name) => {
+                // Use pre-computed safe columns, or '*' if no omitted fields
+                const safeColumns = resAnno.getAssociationSafeColumns(name) ?? ["*"];
+                return {
+                    ref: [name],
+                    expand: safeColumns,
+                };
+            });
+            // Use safe columns for main entity too
+            const mainColumns = resAnno.safeColumns;
+            if (args.select?.length) {
+                // Filter user's select to only safe columns
+                const safeSelect = args.select.filter((field) => !resAnno.omittedFields?.has(field));
+                qy = qy.columns(...safeSelect, ...expandColumns);
+            }
+            else if (mainColumns[0] === "*") {
+                qy = qy.columns("*", ...expandColumns);
+            }
+            else {
+                qy = qy.columns(...mainColumns, ...expandColumns);
+            }
+        }
+        else if (args.select?.length) {
+            qy = qy.columns(...args.select);
+        }
+    }
+    else if (args.select?.length) {
         qy = qy.columns(...args.select);
     }
     if (args.orderby?.length) {

package/lib/mcp/factory.js

@@ -24,8 +24,10 @@ function createMcpServer(config, annotations) {
     const server = new mcp_js_1.McpServer({
         name: config.name,
         version: config.version,
+    }, {
+        instructions: (0, instructions_1.getMcpInstructions)(config),
         capabilities: config.capabilities,
-    }, { instructions: (0, instructions_1.getMcpInstructions)(config) });
+    });
     if (!annotations) {
         logger_1.LOGGER.debug("No annotations provided, skipping registration...");
         return server;

package/lib/mcp/resources.js

@@ -82,6 +82,23 @@ function assignResourceToServer(model, server, authEnabled) {
                         const validatedOrderBy = validator.validateOrderBy(v);
                         query.orderBy(validatedOrderBy);
                         continue;
+                    case "expand":
+                        // Handle expand for associations
+                        const validatedExpand = validator.validateExpand(v);
+                        // Replace '*' with safe columns for each association
+                        const safeExpandColumns = validatedExpand.map((assoc) => {
+                            const assocName = assoc.ref?.[0];
+                            const safeCols = model.getAssociationSafeColumns?.(assocName) ?? ["*"];
+                            return {
+                                ref: assoc.ref,
+                                expand: safeCols,
+                            };
+                        });
+                        // Use main entity's safe columns
+                        const mainSafe = model.safeColumns ?? ["*"];
+                        const cols = query.SELECT?.columns || mainSafe;
+                        query.columns(...cols, ...safeExpandColumns);
+                        continue;
                     default:
                         continue;
                 }

package/lib/mcp/utils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.determineMcpParameterType = determineMcpParameterType;
+exports.buildDeepInsertZodType = buildDeepInsertZodType;
 exports.handleMcpSessionRequest = handleMcpSessionRequest;
 exports.writeODataDescriptionForResource = writeODataDescriptionForResource;
 exports.toolError = toolError;
@@ -22,13 +23,13 @@ function determineMcpParameterType(cdsType, key, target) {
         case "UUID":
             return zod_1.z.string();
         case "Date":
-            return zod_1.z.date();
+            return zod_1.z.coerce.date();
         case "Time":
-            return zod_1.z.date();
+            return zod_1.z.coerce.date();
         case "DateTime":
-            return zod_1.z.date();
+            return zod_1.z.coerce.date();
         case "Timestamp":
-            return zod_1.z.number();
+            return zod_1.z.coerce.date();
         case "Integer":
             return zod_1.z.number();
         case "Int16":
@@ -56,13 +57,13 @@ function determineMcpParameterType(cdsType, key, target) {
         case "StringArray":
             return zod_1.z.array(zod_1.z.string());
         case "DateArray":
-            return zod_1.z.array(zod_1.z.date());
+            return zod_1.z.array(zod_1.z.coerce.date());
         case "TimeArray":
-            return zod_1.z.array(zod_1.z.date());
+            return zod_1.z.array(zod_1.z.coerce.date());
         case "DateTimeArray":
-            return zod_1.z.array(zod_1.z.date());
+            return zod_1.z.array(zod_1.z.coerce.date());
         case "TimestampArray":
-            return zod_1.z.array(zod_1.z.number());
+            return zod_1.z.array(zod_1.z.coerce.date());
         case "UUIDArray":
             return zod_1.z.array(zod_1.z.string());
         case "IntegerArray":
@@ -148,6 +149,43 @@ function buildCompositionZodType(key, target) {
     const zodType = zod_1.z.object(Object.fromEntries(compProperties));
     return isArray ? zod_1.z.array(zodType) : zodType;
 }
+/**
+ * Builds a Zod schema for deep insert by referencing another entity's schema
+ * Similar to buildCompositionZodType but works with explicit entity references
+ * @param targetEntityName - Full entity name (e.g., 'OnPremiseBookingService.BookingItems')
+ * @returns ZodType array schema for the target entity
+ */
+function buildDeepInsertZodType(targetEntityName) {
+    const model = cds.model;
+    if (!model.definitions || !targetEntityName) {
+        return zod_1.z.array(zod_1.z.object({})); // fallback
+    }
+    const targetDef = model.definitions[targetEntityName];
+    if (!targetDef || !targetDef.elements) {
+        return zod_1.z.array(zod_1.z.object({}));
+    }
+    const itemProperties = new Map();
+    for (const [k, v] of Object.entries(targetDef.elements)) {
+        if (!v.type)
+            continue;
+        const elementKeys = new Map(Object.keys(v).map((el) => [el.toLowerCase(), el]));
+        // Skip computed fields
+        const isComputed = elementKeys.has("@core.computed") &&
+            v[elementKeys.get("@core.computed") ?? ""] === true;
+        if (isComputed)
+            continue;
+        const parsedType = v.type.replace("cds.", "");
+        // Skip associations and compositions in deep insert items
+        if (parsedType === "Association" || parsedType === "Composition")
+            continue;
+        // Make all non-key fields optional (consistent with direct entity create)
+        // This ensures external services with notNull on all fields don't require all fields
+        const paramType = determineMcpParameterType(parsedType);
+        itemProperties.set(k, v.key ? paramType : paramType.optional());
+    }
+    const zodType = zod_1.z.object(Object.fromEntries(itemProperties));
+    return zod_1.z.array(zodType); // Always return array for deep insert
+}
 /**
  * Handles incoming MCP session requests by validating session IDs and routing to appropriate session
  * @param req - Express request object containing session headers
@@ -191,6 +229,9 @@ function writeODataDescriptionForResource(model) {
     if (model.functionalities.has("orderby")) {
         description += `- orderby: OData $orderby syntax (e.g., "$orderby=property1 asc", or "$orderby=property1 desc")${constants_1.NEW_LINE}`;
     }
+    if (model.functionalities.has("expand")) {
+        description += `- expand: OData $expand syntax to include related associations (e.g., $expand=* for all, or $expand=property1,property2 for specific ones)${constants_1.NEW_LINE}`;
+    }
     description += `${constants_1.NEW_LINE}Available properties on ${model.target}: ${constants_1.NEW_LINE}`;
     for (const [key, type] of model.properties.entries()) {
         description += `- ${key} -> value type = ${type} ${constants_1.NEW_LINE}`;

package/lib/mcp/validation.js

@@ -146,6 +146,42 @@ class ODataQueryValidator {
         }
         return validated;
     }
+    /**
+     * Validates and sanitizes the $expand query parameter
+     * @param value - Expand parameter: '*' for all associations, or comma-separated list
+     * @returns Array of CQN column objects with expand configuration
+     * @throws Error if any association name is invalid or not allowed
+     */
+    validateExpand(value) {
+        const decoded = decodeURIComponent(value).trim();
+        // Get available associations from the entity
+        const availableAssociations = Array.from(this.allowedTypes.entries())
+            .filter(([, cdsType]) => String(cdsType).toLowerCase().includes("association"))
+            .map(([name]) => name);
+        if (availableAssociations.length === 0) {
+            throw new Error("No associations available for expansion");
+        }
+        // Parse expand parameter: '*' for all, or comma-separated list
+        const expandList = decoded === "*"
+            ? availableAssociations
+            : decoded
+                .split(",")
+                .map((e) => e.trim())
+                .filter((e) => {
+                if (!availableAssociations.includes(e)) {
+                    throw new Error(`Invalid expand association: ${e}. Available associations: ${availableAssociations.join(", ")}`);
+                }
+                return true;
+            });
+        if (expandList.length === 0) {
+            throw new Error("No valid associations specified for expansion");
+        }
+        // Return CQN column objects for expansion
+        return expandList.map((name) => ({
+            ref: [name],
+            expand: ["*"],
+        }));
+    }
     /**
      * Validates and sanitizes the $filter query parameter with comprehensive security checks
      * Prevents injection attacks, validates operators and property references

package/lib/mcp.js

@@ -25,6 +25,8 @@ class McpPlugin {
     config;
     expressApp;
     annotations;
+    static _instance;
+    static isInitializing = false;
     /**
      * Creates a new MCP plugin instance with configuration and session management
      */
@@ -168,5 +170,38 @@ class McpPlugin {
             }
         });
     }
+    /**
+     * Get McpPlugin Instance
+     *
+     * @description  Double Lock singleton initialization.
+     * @returns McpPlugin
+     */
+    static getInstance() {
+        if (!McpPlugin._instance) {
+            if (!McpPlugin.isInitializing) {
+                McpPlugin.isInitializing = true;
+                if (!McpPlugin._instance) {
+                    McpPlugin._instance = new McpPlugin();
+                }
+                McpPlugin.isInitializing = false;
+            }
+            else {
+                /**
+                 * Busy Wait if it is initializing
+                 */
+                while (McpPlugin.isInitializing) { }
+                /**
+                 * check if not init, call again.
+                 */
+                if (!McpPlugin._instance) {
+                    return McpPlugin.getInstance();
+                }
+            }
+        }
+        return McpPlugin._instance;
+    }
+    static resetInstance() {
+        McpPlugin._instance = undefined;
+    }
 }
 exports.default = McpPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavdi/cap-mcp",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "MCP Plugin for CAP",
   "keywords": [
     "MCP",
@@ -38,14 +38,16 @@
     "format": "prettier --check ./src",
     "format:fix": "prettier --write ./src \"**/*.json\"",
     "build:watch": "tsc --watch",
-    "release": "release-it"
+    "release": "release-it",
+    "docs:serve": "docsify serve docs",
+    "docs:links": "markdown-link-check docs/**/*.md"
   },
   "peerDependencies": {
-    "@sap/cds": "^9",
+    "@sap/cds": ">=9",
     "express": "^4"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.19.1",
+    "@modelcontextprotocol/sdk": "^1.23.0",
     "@sap/xssec": "^4.9.1",
     "cors": "^2.8.5",
     "helmet": "^8.1.0",
@@ -61,10 +63,12 @@
     "@types/node": "^24.0.3",
     "@types/sinon": "^17.0.4",
     "@types/supertest": "^6.0.2",
+    "docsify-cli": "^4.4.4",
     "eslint": "^9.29.0",
     "husky": "^9.1.7",
     "jest": "^29.7.0",
     "lint-staged": "^16.1.2",
+    "markdown-link-check": "^3.14.1",
     "prettier": "^3.5.3",
     "release-it": "^19.0.4",
     "sinon": "^21.0.0",