@gavdi/cap-mcp 1.0.1 → 1.1.0

package/cds-plugin.js

@@ -1,5 +1,9 @@
 const cds = global.cds; // enforce host app cds instance
 const McpPlugin = require("./lib/mcp").default;
+const McpBuild = require("./lib/config/build");
+
+// Build tasks
+McpBuild.registerBuildTask();
 
 const plugin = new McpPlugin();
 

package/lib/annotations/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ALL_RESOURCE_OPTIONS = exports.CDS_AUTH_ANNOTATIONS = exports.MCP_ANNOTATION_PROPS = exports.MCP_ANNOTATION_KEY = void 0;
+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
@@ -11,33 +11,27 @@ exports.DEFAULT_ALL_RESOURCE_OPTIONS = exports.CDS_AUTH_ANNOTATIONS = exports.MC
  */
 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
+ * Mapping of the custom annotations + CDS specific annotations and their correlated mapping for MCP usage
  */
-exports.MCP_ANNOTATION_PROPS = {
-    /** Name identifier annotation - required for all MCP elements */
-    MCP_NAME: "@mcp.name",
-    /** Description annotation - required for all MCP elements */
-    MCP_DESCRIPTION: "@mcp.description",
-    /** Resource configuration annotation for CAP entities */
-    MCP_RESOURCE: "@mcp.resource",
-    /** Tool configuration annotation for CAP functions/actions */
-    MCP_TOOL: "@mcp.tool",
-    /** Prompt templates annotation for CAP services */
-    MCP_PROMPT: "@mcp.prompts",
-    /** Wrapper configuration for exposing entities as tools */
-    MCP_WRAP: "@mcp.wrap",
-    /** Elicited user input annotation for tools in CAP services */
-    MCP_ELICIT: "@mcp.elicit",
-};
-/**
- * Set of annotations used for CDS auth annotations
- * Maps logical names to their actual annotation keys used in CDS files.
- */
-exports.CDS_AUTH_ANNOTATIONS = {
-    REQUIRES: "@requires",
-    RESTRICT: "@restrict",
-};
+exports.MCP_ANNOTATION_MAPPING = new Map([
+    ["@mcp.name", "name"],
+    ["@mcp.description", "description"],
+    ["@mcp.resource", "resource"],
+    ["@mcp.tool", "tool"],
+    ["@mcp.prompts", "prompts"],
+    ["@mcp.wrap", "wrap"],
+    ["@mcp.wrap.tools", "wrap.tools"],
+    ["@mcp.wrap.modes", "wrap.modes"],
+    ["@mcp.wrap.hint", "wrap.hint"],
+    ["@mcp.wrap.hint.get", "wrap.hint.get"],
+    ["@mcp.wrap.hint.query", "wrap.hint.query"],
+    ["@mcp.wrap.hint.create", "wrap.hint.create"],
+    ["@mcp.wrap.hint.update", "wrap.hint.update"],
+    ["@mcp.wrap.hint.delete", "wrap.hint.delete"],
+    ["@mcp.elicit", "elicit"],
+    ["@requires", "requires"],
+    ["@restrict", "restrict"],
+]);
 /**
  * Default set of all available OData query options for MCP resources
  * Used when @mcp.resource is set to `true` to enable all capabilities

package/lib/annotations/parser.js

@@ -22,7 +22,7 @@ function parseDefinitions(model) {
         const def = value;
         const parsedAnnotations = parseAnnotations(def);
         const { serviceName, target } = (0, utils_1.splitDefinitionName)(key);
-        parseBoundOperations(serviceName, target, def, result); // Mutates result map with bound operations
+        parseBoundOperations(model, serviceName, target, def, result); // Mutates result map with bound operations
         if (!parsedAnnotations || !(0, utils_1.containsRequiredAnnotations)(parsedAnnotations)) {
             continue; // This check must occur here, since we do want the bound operations even if the parent is not annotated
         }
@@ -42,13 +42,13 @@ function parseDefinitions(model) {
                 result.set(resourceAnnotation.target, resourceAnnotation);
                 continue;
             case "function":
-                const functionAnnotation = constructToolAnnotation(serviceName, target, verifiedAnnotations);
+                const functionAnnotation = constructToolAnnotation(model, serviceName, target, verifiedAnnotations);
                 if (!functionAnnotation)
                     continue;
                 result.set(functionAnnotation.target, functionAnnotation);
                 continue;
             case "action":
-                const actionAnnotation = constructToolAnnotation(serviceName, target, verifiedAnnotations);
+                const actionAnnotation = constructToolAnnotation(model, serviceName, target, verifiedAnnotations);
                 if (!actionAnnotation)
                     continue;
                 result.set(actionAnnotation.target, actionAnnotation);
@@ -65,6 +65,40 @@ function parseDefinitions(model) {
     }
     return result;
 }
+function mapToMcpAnnotationStructure(obj) {
+    const result = {};
+    // Helper function to set nested properties
+    const setNestedValue = (target, path, value) => {
+        const keys = path.split(".");
+        const lastKey = keys.pop();
+        const nestedTarget = keys.reduce((current, key) => {
+            if (!(key in current)) {
+                current[key] = {};
+            }
+            return current[key];
+        }, target);
+        // If the target already has a value and both are objects, merge them
+        if (typeof nestedTarget[lastKey] === "object" &&
+            typeof value === "object" &&
+            nestedTarget[lastKey] !== null &&
+            value !== null &&
+            !Array.isArray(nestedTarget[lastKey]) &&
+            !Array.isArray(value)) {
+            nestedTarget[lastKey] = { ...nestedTarget[lastKey], ...value };
+        }
+        else {
+            nestedTarget[lastKey] = value;
+        }
+    };
+    // Loop through object keys and map them
+    for (const key in obj) {
+        if (constants_1.MCP_ANNOTATION_MAPPING.has(key)) {
+            const mappedPath = constants_1.MCP_ANNOTATION_MAPPING.get(key);
+            setNestedValue(result, mappedPath, obj[key]);
+        }
+    }
+    return result;
+}
 /**
  * Parses MCP annotations from a definition object
  * @param definition - The definition object to parse annotations from
@@ -73,50 +107,11 @@ function parseDefinitions(model) {
 function parseAnnotations(definition) {
     if (!(0, utils_1.containsMcpAnnotation)(definition))
         return undefined;
+    const parsed = mapToMcpAnnotationStructure(definition);
     const annotations = {
         definition: definition,
+        ...parsed,
     };
-    for (const [k, v] of Object.entries(definition)) {
-        // Process MCP annotations and CDS auth annotations
-        if (!k.includes(constants_1.MCP_ANNOTATION_KEY) &&
-            !k.startsWith("@requires") &&
-            !k.startsWith("@restrict")) {
-            continue;
-        }
-        logger_1.LOGGER.debug("Parsing: ", k, v);
-        switch (k) {
-            case constants_1.MCP_ANNOTATION_PROPS.MCP_NAME:
-                annotations.name = v;
-                continue;
-            case constants_1.MCP_ANNOTATION_PROPS.MCP_DESCRIPTION:
-                annotations.description = v;
-                continue;
-            case constants_1.MCP_ANNOTATION_PROPS.MCP_RESOURCE:
-                annotations.resource = v;
-                continue;
-            case constants_1.MCP_ANNOTATION_PROPS.MCP_TOOL:
-                annotations.tool = v;
-                continue;
-            case constants_1.MCP_ANNOTATION_PROPS.MCP_PROMPT:
-                annotations.prompts = v;
-                continue;
-            case constants_1.MCP_ANNOTATION_PROPS.MCP_WRAP:
-                // Wrapper container to expose resources as tools
-                annotations.wrap = v;
-                continue;
-            case constants_1.MCP_ANNOTATION_PROPS.MCP_ELICIT:
-                annotations.elicit = v;
-                continue;
-            case constants_1.CDS_AUTH_ANNOTATIONS.REQUIRES:
-                annotations.requires = v;
-                continue;
-            case constants_1.CDS_AUTH_ANNOTATIONS.RESTRICT:
-                annotations.restrict = v;
-                continue;
-            default:
-                continue;
-        }
-    }
     return annotations;
 }
 /**
@@ -144,10 +139,10 @@ function constructResourceAnnotation(serviceName, target, annotations, definitio
  * @param keyParams - Optional key parameters for bound operations
  * @returns Tool annotation or undefined if invalid
  */
-function constructToolAnnotation(serviceName, target, annotations, entityKey, keyParams) {
+function constructToolAnnotation(model, serviceName, target, annotations, entityKey, keyParams) {
     if (!(0, utils_1.isValidToolAnnotation)(annotations))
         return undefined;
-    const { parameters, operationKind } = (0, utils_1.parseOperationElements)(annotations);
+    const { parameters, operationKind } = (0, utils_1.parseOperationElements)(annotations, model);
     const restrictions = (0, utils_1.parseCdsRestrictions)(annotations.restrict, annotations.requires);
     return new structures_1.McpToolAnnotation(annotations.name, annotations.description, target, serviceName, parameters, entityKey, operationKind, keyParams, restrictions, annotations.elicit);
 }
@@ -170,7 +165,7 @@ function constructPromptAnnotation(serviceName, annotations) {
  * @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) {
+function parseBoundOperations(model, serviceName, entityKey, definition, resultRef) {
     if (definition.kind !== "entity")
         return;
     const boundOperations = definition
@@ -192,7 +187,7 @@ function parseBoundOperations(serviceName, entityKey, definition, resultRef) {
             continue;
         }
         const verifiedAnnotations = parsedAnnotations;
-        const toolAnnotation = constructToolAnnotation(serviceName, k, verifiedAnnotations, entityKey, keyParams);
+        const toolAnnotation = constructToolAnnotation(model, serviceName, k, verifiedAnnotations, entityKey, keyParams);
         if (!toolAnnotation)
             continue;
         resultRef.set(k, toolAnnotation);

package/lib/annotations/utils.js

@@ -175,13 +175,25 @@ function parseResourceElements(definition) {
  * @param annotations - The annotation structure to parse
  * @returns Object containing parameters and operation kind
  */
-function parseOperationElements(annotations) {
+function parseOperationElements(annotations, model) {
     let parameters;
+    const parseParam = (k, v, suffix) => {
+        if (typeof v.type !== "string") {
+            const referencedType = parseTypedReference(v.type, model);
+            parameters?.set(k, `${referencedType}${suffix ?? ""}`);
+            return;
+        }
+        parameters?.set(k, `${v.type.replace("cds.", "")}${suffix ?? ""}`);
+    };
     const params = annotations.definition["params"];
     if (params && Object.entries(params).length > 0) {
         parameters = new Map();
         for (const [k, v] of Object.entries(params)) {
-            parameters.set(k, v.type.replace("cds.", ""));
+            if (v.items) {
+                parseParam(k, v.items, "Array");
+                continue;
+            }
+            parseParam(k, v);
         }
     }
     return {
@@ -189,6 +201,22 @@ function parseOperationElements(annotations) {
         operationKind: annotations.definition.kind,
     };
 }
+/**
+ * Recursively digs through the typed reference object of an operation parameter.
+ * @param param
+ * @param model
+ * @returns string|undefined
+ * @throws Error if nested type is not parseable
+ */
+function parseTypedReference(param, model) {
+    if (!param || !param.ref) {
+        throw new Error("Failed to parse nested type reference");
+    }
+    const referenceType = model.definitions?.[param.ref[0]].elements[param.ref[1]];
+    return typeof referenceType?.type === "string"
+        ? referenceType.type?.replace("cds.", "")
+        : parseTypedReference(referenceType?.type, model);
+}
 /**
  * Parses entity keys from a definition
  * @param definition - The definition to parse keys from

package/lib/config/build.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBuildTask = registerBuildTask;
+const logger_1 = require("../logger");
+const json_parser_1 = require("./json-parser");
+/* @ts-ignore */
+const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
+function registerBuildTask() {
+    cds.build?.register("mcp", class McpBuildPlugin extends cds.build.Plugin {
+        static taskDefaults = {};
+        static instructionsPath;
+        static hasTask() {
+            const config = cds.env.mcp;
+            if (!config) {
+                return false;
+            }
+            else if (typeof config === "object") {
+                this.instructionsPath =
+                    typeof config.instructions === "object"
+                        ? config.instructions.file
+                        : undefined;
+                return (this.instructionsPath !== undefined &&
+                    this.instructionsPath.length > 0);
+            }
+            const parsed = (0, json_parser_1.parseCAPConfiguration)(config);
+            if (!parsed || typeof parsed.instructions !== "object") {
+                return false;
+            }
+            this.instructionsPath =
+                typeof parsed.instructions === "object"
+                    ? parsed.instructions.file
+                    : undefined;
+            return (this.instructionsPath !== undefined &&
+                this.instructionsPath.length > 0);
+        }
+        async build() {
+            logger_1.LOGGER.debug("Performing build task - copy MCP instructions");
+            if (!McpBuildPlugin.instructionsPath) {
+                return;
+            }
+            if (cds.utils.fs.existsSync(this.task.src, McpBuildPlugin.instructionsPath)) {
+                await this.copy(McpBuildPlugin.instructionsPath).to(cds.utils.path.join("srv", McpBuildPlugin.instructionsPath));
+            }
+        }
+    });
+}

package/lib/config/instructions.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMcpInstructions = getMcpInstructions;
+exports.readInstructionsFile = readInstructionsFile;
+const cds_1 = require("@sap/cds");
+function getMcpInstructions(config) {
+    if (!config.instructions) {
+        return undefined;
+    }
+    if (typeof config.instructions === "string") {
+        return config.instructions;
+    }
+    return config.instructions.file
+        ? readInstructionsFile(config.instructions.file)
+        : undefined;
+}
+function readInstructionsFile(path) {
+    if (!containsMarkdownType(path)) {
+        throw new Error("Invalid file type provided for instructions");
+    }
+    else if (!cds_1.utils.fs.existsSync(path)) {
+        throw new Error("Instructions file not found");
+    }
+    const file = cds_1.utils.fs.readFileSync(path);
+    return file.toString("utf8");
+}
+function containsMarkdownType(path) {
+    const extension = path.substring(path.length - 3);
+    return extension === ".md";
+}

package/lib/mcp/entity-tools.js

@@ -247,8 +247,8 @@ function registerQueryTool(resAnno, server, authEnabled) {
         aggregate: inputZod.shape.aggregate,
         explain: inputZod.shape.explain,
     };
-    const hint = resAnno.wrap?.hint ? ` Hint: ${resAnno.wrap?.hint}` : "";
-    const desc = `${buildEnhancedQueryDescription(resAnno)} CRITICAL: Use foreign key fields (e.g., author_ID) for associations - association names (e.g., author) won't work in filters.` +
+    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.` +
         hint;
     const queryHandler = async (rawArgs) => {
         const parsed = inputZod.safeParse(rawArgs);
@@ -298,8 +298,8 @@ function registerGetTool(resAnno, server, authEnabled) {
         inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}`);
     }
     const keyList = Array.from(resAnno.resourceKeys.keys()).join(", ");
-    const hint = resAnno.wrap?.hint ? ` Hint: ${resAnno.wrap?.hint}` : "";
-    const desc = `Get one ${resAnno.target} by key(s): ${keyList}. For fields & examples call cap_describe_model.${hint}`;
+    const hint = constructHintMessage(resAnno, "get");
+    const desc = `Resource description: ${resAnno.description}. Get one ${resAnno.target} by key(s): ${keyList}. For fields & examples call cap_describe_model.${hint}`;
     const getHandler = async (args) => {
         const startTime = Date.now();
         const CDS = global.cds;
@@ -380,8 +380,8 @@ function registerCreateTool(resAnno, server, authEnabled) {
             .optional()
             .describe(`Field ${propName}`);
     }
-    const hint = resAnno.wrap?.hint ? ` Hint: ${resAnno.wrap?.hint}` : "";
-    const desc = `Create a new ${resAnno.target}. Provide fields; service applies defaults.${hint}`;
+    const hint = constructHintMessage(resAnno, "create");
+    const desc = `Resource description: ${resAnno.description}. Create a new ${resAnno.target}. Provide fields; service applies defaults.${hint}`;
     const createHandler = async (args) => {
         const CDS = global.cds;
         const { INSERT } = CDS.ql;
@@ -470,8 +470,8 @@ function registerUpdateTool(resAnno, server, authEnabled) {
             .describe(`Field ${propName}`);
     }
     const keyList = Array.from(resAnno.resourceKeys.keys()).join(", ");
-    const hint = resAnno.wrap?.hint ? ` Hint: ${resAnno.wrap?.hint}` : "";
-    const desc = `Update ${resAnno.target} by key(s): ${keyList}. Provide fields to update.${hint}`;
+    const hint = constructHintMessage(resAnno, "update");
+    const desc = `Resource description: ${resAnno.description}. Update ${resAnno.target} by key(s): ${keyList}. Provide fields to update.${hint}`;
     const updateHandler = async (args) => {
         const CDS = global.cds;
         const { UPDATE } = CDS.ql;
@@ -559,8 +559,8 @@ function registerDeleteTool(resAnno, server, authEnabled) {
         inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}`);
     }
     const keyList = Array.from(resAnno.resourceKeys.keys()).join(", ");
-    const hint = resAnno.wrap?.hint ? ` Hint: ${resAnno.wrap?.hint}` : "";
-    const desc = `Delete ${resAnno.target} by key(s): ${keyList}. This operation cannot be undone.${hint}`;
+    const hint = constructHintMessage(resAnno, "delete");
+    const desc = `Resource description: ${resAnno.description}. Delete ${resAnno.target} by key(s): ${keyList}. This operation cannot be undone.${hint}`;
     const deleteHandler = async (args) => {
         const CDS = global.cds;
         const { DELETE } = CDS.ql;
@@ -703,3 +703,15 @@ async function executeQuery(CDS, svc, args, baseQuery) {
             return svc.run(baseQuery);
     }
 }
+function constructHintMessage(resAnno, wrapAction) {
+    if (!resAnno.wrap?.hint) {
+        return "";
+    }
+    else if (typeof resAnno.wrap.hint === "string") {
+        return ` Hint: ${resAnno.wrap?.hint}`;
+    }
+    if (typeof resAnno.wrap.hint !== "object") {
+        throw new Error(`Unparseable hint provided for entity: ${resAnno.name}`);
+    }
+    return ` Hint: ${resAnno.wrap.hint[wrapAction] ?? ""}`;
+}

package/lib/mcp/factory.js

@@ -12,6 +12,7 @@ const utils_1 = require("../auth/utils");
 // Use relative import without extension for ts-jest resolver compatibility
 const entity_tools_1 = require("./entity-tools");
 const describe_model_1 = require("./describe-model");
+const instructions_1 = require("../config/instructions");
 /**
  * Creates and configures an MCP server instance with the given configuration and annotations
  * @param config - CAP configuration object
@@ -24,7 +25,7 @@ function createMcpServer(config, annotations) {
         name: config.name,
         version: config.version,
         capabilities: config.capabilities,
-    }, { instructions: config.instructions });
+    }, { instructions: (0, instructions_1.getMcpInstructions)(config) });
     if (!annotations) {
         logger_1.LOGGER.debug("No annotations provided, skipping registration...");
         return server;
@@ -51,7 +52,8 @@ function createMcpServer(config, annotations) {
             const localWrap = entry.wrap?.tools;
             const enabled = localWrap === true || (localWrap === undefined && globalWrap);
             if (enabled) {
-                const modes = config.wrap_entity_modes ?? ["query", "get"];
+                const modes = entry.wrap?.modes ??
+                    config.wrap_entity_modes ?? ["query", "get"];
                 (0, entity_tools_1.registerEntityWrappers)(entry, server, authEnabled, modes, accesses);
             }
             continue;

package/lib/mcp/utils.js

@@ -16,10 +16,76 @@ function determineMcpParameterType(cdsType) {
     switch (cdsType) {
         case "String":
             return zod_1.z.string();
+        case "UUID":
+            return zod_1.z.string();
+        case "Date":
+            return zod_1.z.date();
+        case "Time":
+            return zod_1.z.date();
+        case "DateTime":
+            return zod_1.z.date();
+        case "Timestamp":
+            return zod_1.z.number();
         case "Integer":
             return zod_1.z.number();
+        case "Int16":
+            return zod_1.z.number();
+        case "Int32":
+            return zod_1.z.number();
+        case "Int64":
+            return zod_1.z.number();
+        case "UInt8":
+            return zod_1.z.number();
+        case "Decimal":
+            return zod_1.z.number();
+        case "Double":
+            return zod_1.z.number();
         case "Boolean":
             return zod_1.z.boolean();
+        case "Binary":
+            return zod_1.z.string();
+        case "LargeBinary":
+            return zod_1.z.string();
+        case "LargeString":
+            return zod_1.z.string();
+        case "Map":
+            return zod_1.z.any();
+        case "StringArray":
+            return zod_1.z.array(zod_1.z.string());
+        case "DateArray":
+            return zod_1.z.array(zod_1.z.date());
+        case "TimeArray":
+            return zod_1.z.array(zod_1.z.date());
+        case "DateTimeArray":
+            return zod_1.z.array(zod_1.z.date());
+        case "TimestampArray":
+            return zod_1.z.array(zod_1.z.number());
+        case "UUIDArray":
+            return zod_1.z.array(zod_1.z.string());
+        case "IntegerArray":
+            return zod_1.z.array(zod_1.z.number());
+        case "Int16Array":
+            return zod_1.z.array(zod_1.z.number());
+        case "Int32Array":
+            return zod_1.z.array(zod_1.z.number());
+        case "Int64Array":
+            return zod_1.z.array(zod_1.z.number());
+        case "UInt8Array":
+            return zod_1.z.array(zod_1.z.number());
+        case "DecimalArray":
+            return zod_1.z.array(zod_1.z.number());
+        case "BooleanArray":
+            return zod_1.z.array(zod_1.z.boolean());
+        case "DoubleArray":
+            return zod_1.z.array(zod_1.z.number());
+        case "BinaryArray":
+            return zod_1.z.array(zod_1.z.string());
+        case "LargeBinaryArray":
+            return zod_1.z.array(zod_1.z.string());
+        case "LargeStringArray":
+            return zod_1.z.array(zod_1.z.string());
+        case "MapArray":
+            return zod_1.z.array(zod_1.z.any());
         default:
             return zod_1.z.string();
     }

package/package.json

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