@gavdi/cap-mcp 1.1.0 → 1.1.2

package/README.md

@@ -1,4 +1,7 @@
 # CAP MCP Plugin - AI With Ease
+![NPM Version](https://img.shields.io/npm/v/%40gavdi%2Fcap-mcp) ![NPM License](https://img.shields.io/npm/l/%40gavdi%2Fcap-mcp) ![GitHub commits since latest release](https://img.shields.io/github/commits-since/gavdilabs/cap-mcp-plugin/latest)
+
+
 
 > This implementation is based on the Model Context Protocol (MCP) put forward by Anthropic.
 > For more information on MCP, please have a look at their [official documentation.](https://modelcontextprotocol.io/introduction)

package/cds-plugin.js

@@ -12,8 +12,8 @@ cds.on("bootstrap", async (app) => {
   await plugin?.onBootstrap(app);
 });
 
-cds.on("loaded", async (model) => {
-  await plugin?.onLoaded(model);
+cds.on("serving", async () => {
+  await plugin?.onLoaded(cds.model);
 });
 
 cds.on("shutdown", async () => {

package/lib/annotations/parser.js

@@ -36,7 +36,7 @@ function parseDefinitions(model) {
         const verifiedAnnotations = parsedAnnotations;
         switch (def.kind) {
             case "entity":
-                const resourceAnnotation = constructResourceAnnotation(serviceName, target, verifiedAnnotations, def);
+                const resourceAnnotation = constructResourceAnnotation(serviceName, target, verifiedAnnotations, def, model);
                 if (!resourceAnnotation)
                     continue;
                 result.set(resourceAnnotation.target, resourceAnnotation);
@@ -122,13 +122,16 @@ function parseAnnotations(definition) {
  * @param definition - CSN definition object
  * @returns Resource annotation or undefined if invalid
  */
-function constructResourceAnnotation(serviceName, target, annotations, definition) {
+function constructResourceAnnotation(serviceName, target, annotations, definition, model) {
     if (!(0, utils_1.isValidResourceAnnotation)(annotations))
         return undefined;
     const functionalities = (0, utils_1.determineResourceOptions)(annotations);
-    const { properties, resourceKeys } = (0, utils_1.parseResourceElements)(definition);
+    const foreignKeys = new Map(Object.entries(model.definitions?.[`${serviceName}.${target}`].elements ?? {})
+        .filter(([_, v]) => v["@odata.foreignKey4"] !== undefined)
+        .map(([k, v]) => [k, v["@odata.foreignKey4"]]));
+    const { properties, resourceKeys } = (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, annotations.wrap, restrictions);
+    return new structures_1.McpResourceAnnotation(annotations.name, annotations.description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, annotations.wrap, restrictions);
 }
 /**
  * Constructs a tool annotation from parsed annotation data

package/lib/annotations/structures.js

@@ -82,6 +82,8 @@ class McpResourceAnnotation extends McpAnnotation {
     _resourceKeys;
     /** Optional wrapper configuration to expose this resource as tools */
     _wrap;
+    /** Map of foreign keys property -> associated entity */
+    _foreignKeys;
     /**
      * Creates a new MCP resource annotation
      * @param name - Unique identifier for this resource
@@ -91,14 +93,17 @@ class McpResourceAnnotation extends McpAnnotation {
      * @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
+     * @param foreignKeys - Map of foreign keys used by entity
+     * @param wrap - Wrap usage
      * @param restrictions - Optional restrictions based on CDS roles
      */
-    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys, wrap, restrictions) {
+    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, wrap, restrictions) {
         super(name, description, target, serviceName, restrictions ?? []);
         this._functionalities = functionalities;
         this._properties = properties;
         this._resourceKeys = resourceKeys;
         this._wrap = wrap;
+        this._foreignKeys = foreignKeys;
     }
     /**
      * Gets the set of enabled OData query functionalities
@@ -107,6 +112,13 @@ class McpResourceAnnotation extends McpAnnotation {
     get functionalities() {
         return this._functionalities;
     }
+    /**
+     * Gets the map of foreign keys used withing the resource
+     * @returns Map of foreign keys - property name -> associated entity
+     */
+    get foreignKeys() {
+        return this._foreignKeys;
+    }
     /**
      * Gets the map of entity properties to their CDS types
      * @returns Map of property names to type strings

package/lib/annotations/utils.js

@@ -153,17 +153,33 @@ function determineResourceOptions(annotations) {
  * @param definition - The definition to parse
  * @returns Object containing properties and resource keys maps
  */
-function parseResourceElements(definition) {
+function parseResourceElements(definition, model) {
     const properties = new Map();
     const resourceKeys = new Map();
-    for (const [key, value] of Object.entries(definition.elements || {})) {
-        if (!value.type)
+    const parseParam = (k, v, suffix) => {
+        let result = "";
+        if (typeof v.type !== "string") {
+            const referencedType = parseTypedReference(v.type, model);
+            result = `${referencedType}${suffix ?? ""}`;
+        }
+        else {
+            result = `${v.type.replace("cds.", "")}${suffix ?? ""}`;
+        }
+        properties?.set(k, result);
+        return result;
+    };
+    for (const [k, v] of Object.entries(definition.elements || {})) {
+        if (v.items) {
+            const result = parseParam(k, v.items, "Array");
+            if (!v.key)
+                continue;
+            resourceKeys.set(k, result);
             continue;
-        const parsedType = value.type.replace("cds.", "");
-        properties.set(key, parsedType);
-        if (!value.key)
+        }
+        const result = parseParam(k, v);
+        if (!v.key || v.type === "cds.Association")
             continue;
-        resourceKeys.set(key, parsedType);
+        resourceKeys.set(k, result);
     }
     return {
         properties,

package/lib/mcp/describe-model.js

@@ -30,24 +30,26 @@ function registerDescribeModelTool(server) {
         const refl = CDS.reflect(CDS.model);
         const listServices = () => {
             const names = Object.values(CDS.services || {})
-                .map((s) => s?.definition?.name || s?.name)
+                .map((s) => s?.namespace || s?.definition?.name || s?.name)
                 .filter(Boolean);
             return { services: [...new Set(names)].sort() };
         };
         const listEntities = (service) => {
-            const all = Object.values(refl.entities || {}) || [];
+            const all = Object.entries(refl.definitions || {})
+                .filter((x) => x[1].kind == "entity" && !x[0].startsWith("cds.")) // ignore entities such as "cds.outbox.Messages"
+                .map((x) => x[0]);
             const filtered = service
-                ? all.filter((e) => String(e.name).startsWith(service + "."))
+                ? all.filter((e) => e.startsWith(service + "."))
                 : all;
             return {
-                entities: filtered.map((e) => e.name).sort(),
+                entities: filtered.sort(),
             };
         };
         const describeEntity = (service, entity) => {
             if (!entity)
                 return { error: "Please provide 'entity'." };
             const fqn = service && !entity.includes(".") ? `${service}.${entity}` : entity;
-            const ent = (refl.entities || {})[fqn] || (refl.entities || {})[entity];
+            const ent = (refl.definitions || {})[fqn] || (refl.definitions || {})[entity];
             if (!ent)
                 return {
                     error: `Entity not found: ${entity}${service ? ` (service ${service})` : ""}`,

package/lib/mcp/entity-tools.js

@@ -83,23 +83,6 @@ function buildEnhancedQueryDescription(resAnno) {
         : "";
     return baseDesc + assocHint;
 }
-/**
- * Builds field documentation for schema descriptions
- */
-function buildFieldDocumentation(resAnno) {
-    const docs = [];
-    for (const [propName, cdsType] of resAnno.properties.entries()) {
-        const isAssociation = String(cdsType).toLowerCase().includes("association");
-        if (isAssociation) {
-            docs.push(`${propName}(association: compare by key value)`);
-            docs.push(`${propName}_ID(foreign key for ${propName})`);
-        }
-        else {
-            docs.push(`${propName}(${String(cdsType).toLowerCase()})`);
-        }
-    }
-    return docs.join(", ");
-}
 /**
  * Registers CRUD-like MCP tools for an annotated entity (resource).
  * Modes can be controlled globally via configuration and per-entity via @mcp.wrap.
@@ -158,13 +141,6 @@ function registerQueryTool(resAnno, server, authEnabled) {
     const scalarKeys = Array.from(resAnno.properties.entries())
         .filter(([, cdsType]) => !String(cdsType).toLowerCase().includes("association"))
         .map(([name]) => name);
-    // Add foreign key fields for associations to scalar keys for select/orderby
-    for (const [propName, cdsType] of resAnno.properties.entries()) {
-        const isAssociation = String(cdsType).toLowerCase().includes("association");
-        if (isAssociation) {
-            scalarKeys.push(`${propName}_ID`);
-        }
-    }
     // Build where field enum: use same fields as select (scalar + foreign keys)
     // This ensures consistency - what you can select, you can filter by
     const whereKeys = [...scalarKeys];
@@ -369,16 +345,14 @@ function registerCreateTool(resAnno, server, authEnabled) {
     for (const [propName, cdsType] of resAnno.properties.entries()) {
         const isAssociation = String(cdsType).toLowerCase().includes("association");
         if (isAssociation) {
-            // Prefer foreign key input for associations: <assoc>_ID
-            inputSchema[`${propName}_ID`] = zod_1.z
-                .number()
-                .describe(`Foreign key for association ${propName}`)
-                .optional();
+            // Association keys are supplied directly from model loading as of v1.1.2
             continue;
         }
-        inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType)
+        inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType, propName, `${resAnno.serviceName}.${resAnno.target}`)
             .optional()
-            .describe(`Field ${propName}`);
+            .describe(resAnno.foreignKeys.has(propName)
+            ? `Foreign key to ${resAnno.foreignKeys.get(propName)} on ${propName}`
+            : `Field ${propName}`);
     }
     const hint = constructHintMessage(resAnno, "create");
     const desc = `Resource description: ${resAnno.description}. Create a new ${resAnno.target}. Provide fields; service applies defaults.${hint}`;
@@ -459,15 +433,14 @@ function registerUpdateTool(resAnno, server, authEnabled) {
             continue;
         const isAssociation = String(cdsType).toLowerCase().includes("association");
         if (isAssociation) {
-            inputSchema[`${propName}_ID`] = zod_1.z
-                .number()
-                .describe(`Foreign key for association ${propName}`)
-                .optional();
+            // Association keys are supplied directly from model loading as of v1.1.2
             continue;
         }
-        inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType)
+        inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType, propName, `${resAnno.serviceName}.${resAnno.target}`)
             .optional()
-            .describe(`Field ${propName}`);
+            .describe(resAnno.foreignKeys.has(propName)
+            ? `Foreign key to ${resAnno.foreignKeys.get(propName)} on ${propName}`
+            : `Field ${propName}`);
     }
     const keyList = Array.from(resAnno.resourceKeys.keys()).join(", ");
     const hint = constructHintMessage(resAnno, "update");
@@ -687,7 +660,11 @@ async function executeQuery(CDS, svc, args, baseQuery) {
     const { SELECT } = CDS.ql;
     switch (args.return) {
         case "count": {
-            const countQuery = SELECT.from(baseQuery.SELECT.from).columns("count(1) as count");
+            const countQuery = SELECT.from(baseQuery.SELECT.from)
+                .columns("count(1) as count")
+                .where(baseQuery.SELECT.where)
+                .limit(baseQuery.SELECT.limit?.rows?.val, baseQuery.SELECT.limit?.offset?.val)
+                .orderBy(baseQuery.SELECT.orderBy);
             const result = await svc.run(countQuery);
             const row = Array.isArray(result) ? result[0] : result;
             return { count: row?.count ?? 0 };
@@ -696,11 +673,15 @@ async function executeQuery(CDS, svc, args, baseQuery) {
             if (!args.aggregate?.length)
                 return [];
             const cols = args.aggregate.map((a) => `${a.fn}(${a.field}) as ${a.fn}_${a.field}`);
-            const aggQuery = SELECT.from(baseQuery.SELECT.from).columns(...cols);
-            return svc.run(aggQuery);
+            const aggQuery = SELECT.from(baseQuery.SELECT.from)
+                .columns(...cols)
+                .where(baseQuery.SELECT.where)
+                .limit(baseQuery.SELECT.limit?.rows?.val, baseQuery.SELECT.limit?.offset?.val)
+                .orderBy(baseQuery.SELECT.orderBy);
+            return await svc.run(aggQuery);
         }
         default:
-            return svc.run(baseQuery);
+            return await svc.run(baseQuery);
     }
 }
 function constructHintMessage(resAnno, wrapAction) {

package/lib/mcp/utils.js

@@ -7,12 +7,14 @@ exports.toolError = toolError;
 exports.asMcpResult = asMcpResult;
 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
 /**
  * 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) {
+function determineMcpParameterType(cdsType, key, target) {
     switch (cdsType) {
         case "String":
             return zod_1.z.string();
@@ -49,7 +51,7 @@ function determineMcpParameterType(cdsType) {
         case "LargeString":
             return zod_1.z.string();
         case "Map":
-            return zod_1.z.any();
+            return zod_1.z.object({});
         case "StringArray":
             return zod_1.z.array(zod_1.z.string());
         case "DateArray":
@@ -85,11 +87,45 @@ function determineMcpParameterType(cdsType) {
         case "LargeStringArray":
             return zod_1.z.array(zod_1.z.string());
         case "MapArray":
-            return zod_1.z.array(zod_1.z.any());
+            return zod_1.z.array(zod_1.z.object({}));
+        case "Composition":
+            return buildCompositionZodType(key, target);
         default:
             return zod_1.z.string();
     }
 }
+/**
+ * Builds the complex ZodType for a CDS type of 'Composition'
+ * @param key
+ * @param target
+ * @returns ZodType
+ */
+function buildCompositionZodType(key, target) {
+    const model = cds.model;
+    if (!model.definitions || !target || !key) {
+        return zod_1.z.object({}); // fallback, might have to reconsider type later
+    }
+    const targetDef = model.definitions[target];
+    const targetProp = targetDef.elements[key];
+    const comp = model.definitions[targetProp.target];
+    if (!comp) {
+        return zod_1.z.object({});
+    }
+    const isArray = targetProp.cardinality !== undefined;
+    const compProperties = new Map();
+    for (const [k, v] of Object.entries(comp.elements)) {
+        if (!v.type)
+            continue;
+        const parsedType = v.type.replace("cds.", "");
+        if (parsedType === "Association" || parsedType === "Composition")
+            continue; // We will not support nested compositions for now
+        const isOptional = !v.key && !v.notNull;
+        const paramType = determineMcpParameterType(parsedType);
+        compProperties.set(k, isOptional ? paramType.optional() : paramType);
+    }
+    const zodType = zod_1.z.object(Object.fromEntries(compProperties));
+    return isArray ? zod_1.z.array(zodType) : zodType;
+}
 /**
  * Handles incoming MCP session requests by validating session IDs and routing to appropriate session
  * @param req - Express request object containing session headers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavdi/cap-mcp",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "MCP Pluging for CAP",
   "keywords": [
     "MCP",