@gavdi/cap-mcp 0.9.9 → 0.10.1

package/README.md

@@ -120,6 +120,7 @@ This plugin transforms your annotated CAP services into a fully functional MCP s
 - **🔧 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
 - **💡 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
 - **⚙️ Flexible Configuration**: Support for custom parameter sets and descriptions
 
@@ -231,6 +232,52 @@ extend projection Books with actions {
 }
 ```
 
+#### Tool Elicitation
+
+Request user confirmation or input before tool execution using the `elicit` property:
+
+```cds
+// Request user confirmation before execution
+@mcp: {
+  name       : 'book-recommendation',
+  description: 'Get a random book recommendation',
+  tool       : true,
+  elicit     : ['confirm']
+}
+function getBookRecommendation() returns String;
+
+// Request user input for parameters
+@mcp: {
+  name       : 'get-author',
+  description: 'Gets the desired author',
+  tool       : true,
+  elicit     : ['input']
+}
+function getAuthor(id: String) returns String;
+
+// Request both input and confirmation
+@mcp: {
+  name       : 'books-by-author',
+  description: 'Gets a list of books made by the author',
+  tool       : true,
+  elicit     : ['input', 'confirm']
+}
+function getBooksByAuthor(authorName: String) returns array of String;
+```
+
+> NOTE: Elicitation is only available for direct tools at this moment. Wrapped entities are not covered by this.
+
+**Elicit Types:**
+- **`confirm`**: Requests user confirmation before executing the tool with a yes/no prompt
+- **`input`**: Prompts the user to provide values for the tool's parameters
+- **Combined**: Use both `['input', 'confirm']` to first collect parameters, then ask for confirmation
+
+**User Experience:**
+- **Confirmation**: "Please confirm that you want to perform action 'Get a random book recommendation'"
+- **Input**: "Please fill out the required parameters" with a form for each parameter
+- **User Actions**: Accept, decline, or cancel the elicitation request
+- **Early Exit**: Tools return appropriate messages if declined or cancelled
+
 ### Prompt Templates
 
 Define reusable AI prompt templates:

package/lib/annotations/constants.js

@@ -27,6 +27,8 @@ exports.MCP_ANNOTATION_PROPS = {
     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

package/lib/annotations/parser.js

@@ -26,6 +26,13 @@ function parseDefinitions(model) {
         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
         }
+        // Set the target in annotations for error reporting
+        if (parsedAnnotations) {
+            parsedAnnotations.target = key;
+        }
+        if (!(0, utils_1.containsRequiredElicitedParams)(parsedAnnotations)) {
+            continue; // Really doesn't do anything as the method will throw if the implementation is invalid
+        }
         const verifiedAnnotations = parsedAnnotations;
         switch (def.kind) {
             case "entity":
@@ -97,6 +104,9 @@ function parseAnnotations(definition) {
                 // 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;
@@ -139,7 +149,7 @@ function constructToolAnnotation(serviceName, target, annotations, entityKey, ke
         return undefined;
     const { parameters, operationKind } = (0, utils_1.parseOperationElements)(annotations);
     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);
+    return new structures_1.McpToolAnnotation(annotations.name, annotations.description, target, serviceName, parameters, entityKey, operationKind, keyParams, restrictions, annotations.elicit);
 }
 /**
  * Constructs a prompt annotation from parsed annotation data
@@ -172,7 +182,13 @@ function parseBoundOperations(serviceName, entityKey, definition, resultRef) {
         if (v.kind !== "function" && v.kind !== "action")
             continue;
         const parsedAnnotations = parseAnnotations(v);
-        if (!parsedAnnotations || !(0, utils_1.containsRequiredAnnotations)(parsedAnnotations)) {
+        // Set the target in annotations for error reporting
+        if (parsedAnnotations) {
+            parsedAnnotations.target = k;
+        }
+        if (!parsedAnnotations ||
+            !(0, utils_1.containsRequiredAnnotations)(parsedAnnotations) ||
+            !(0, utils_1.containsRequiredElicitedParams)(parsedAnnotations)) {
             continue;
         }
         const verifiedAnnotations = parsedAnnotations;

package/lib/annotations/structures.js

@@ -142,6 +142,8 @@ class McpToolAnnotation extends McpAnnotation {
     _operationKind;
     /** Map of key field names to their types for bound operations */
     _keyTypeMap;
+    /** Elicited user input object */
+    _elicits;
     /**
      * Creates a new MCP tool annotation
      * @param name - Unique identifier for this tool
@@ -153,13 +155,15 @@ class McpToolAnnotation extends McpAnnotation {
      * @param operationKind - Optional operation type ('function' or 'action')
      * @param keyTypeMap - Optional map of key fields to types for bound operations
      * @param restrictions - Optional restrictions based on CDS roles
+     * @param elicits - Optional elicited input requirement
      */
-    constructor(name, description, operation, serviceName, parameters, entityKey, operationKind, keyTypeMap, restrictions) {
+    constructor(name, description, operation, serviceName, parameters, entityKey, operationKind, keyTypeMap, restrictions, elicits) {
         super(name, description, operation, serviceName, restrictions ?? []);
         this._parameters = parameters;
         this._entityKey = entityKey;
         this._operationKind = operationKind;
         this._keyTypeMap = keyTypeMap;
+        this._elicits = elicits;
     }
     /**
      * Gets the map of function parameters to their CDS types
@@ -189,6 +193,13 @@ class McpToolAnnotation extends McpAnnotation {
     get keyTypeMap() {
         return this._keyTypeMap;
     }
+    /**
+     * Gets the elicited user input if any is required for the tool
+     * @returns Elicited user input object
+     */
+    get elicits() {
+        return this._elicits;
+    }
 }
 exports.McpToolAnnotation = McpToolAnnotation;
 /**

package/lib/annotations/utils.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.splitDefinitionName = splitDefinitionName;
 exports.containsMcpAnnotation = containsMcpAnnotation;
 exports.containsRequiredAnnotations = containsRequiredAnnotations;
+exports.containsRequiredElicitedParams = containsRequiredElicitedParams;
 exports.isValidResourceAnnotation = isValidResourceAnnotation;
 exports.isValidToolAnnotation = isValidToolAnnotation;
 exports.isValidPromptsAnnotation = isValidPromptsAnnotation;
@@ -55,6 +56,21 @@ function containsRequiredAnnotations(annotations) {
     }
     return true;
 }
+/**
+ * Validates that the required params for MCP elicited user input annotations are valid
+ * @param annotations - The annotation structure to validate
+ * @returns True if valid, throw error if invalid
+ * @throws Error if required annotations are missing
+ */
+function containsRequiredElicitedParams(annotations) {
+    if (!annotations.elicit)
+        return true;
+    const param = annotations.elicit;
+    if (!param || param?.length <= 0) {
+        throw new Error(`Invalid annotation '${annotations.target}' - Incomplete elicited user input`);
+    }
+    return true;
+}
 /**
  * Validates a resource annotation structure
  * @param annotations - The annotation structure to validate
@@ -181,6 +197,8 @@ function parseOperationElements(annotations) {
  */
 function parseEntityKeys(definition) {
     const result = new Map();
+    if (!definition?.elements)
+        return result; // If there is no defined elements, we exit early
     for (const [k, v] of Object.entries(definition.elements)) {
         if (!v.key)
             continue;

package/lib/mcp/elicited-input.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isElicitInput = isElicitInput;
+exports.constructElicitationFunctions = constructElicitationFunctions;
+exports.handleElicitationRequests = handleElicitationRequests;
+const zod_1 = require("zod");
+/**
+ * Message displayed to users when requesting input parameters
+ */
+const INPUT_MSG = "Please fill out the required parameters";
+/**
+ * Checks if the elicited input array contains an 'input' requirement
+ * @param elicits - Array of elicit types or undefined
+ * @returns True if 'input' elicitation is required, false otherwise
+ */
+function isElicitInput(elicits) {
+    return elicits ? elicits.includes("input") : false;
+}
+/**
+ * Constructs elicitation request parameters based on the tool annotation's elicit requirements
+ * @param model - MCP tool annotation containing elicit configuration
+ * @param params - Parameter definitions for the tool
+ * @returns Array of elicit request parameters for MCP server
+ * @throws Error if invalid elicitation type is encountered
+ */
+function constructElicitationFunctions(model, params) {
+    const result = [];
+    for (const el of model.elicits ?? []) {
+        switch (el) {
+            case "input":
+                result.push(constructElicitInput(params));
+                continue;
+            case "confirm":
+                result.push(contructElicitConfirm(model));
+                continue;
+            default:
+                throw new Error("Invalid elicitation type");
+        }
+    }
+    return result;
+}
+/**
+ * Processes multiple elicitation requests sequentially and handles user responses
+ * @param requests - Array of elicit request parameters or undefined
+ * @param server - MCP server instance for making elicit calls
+ * @returns Promise resolving to elicitation response with early exit or data
+ */
+async function handleElicitationRequests(requests, server) {
+    if (!requests || requests.length <= 0) {
+        return { earlyResponse: undefined };
+    }
+    let data = undefined;
+    for (const req of requests) {
+        const res = await server.server.elicitInput(req);
+        const earlyResponse = handleElicitResponse(res);
+        if (earlyResponse) {
+            return { earlyResponse };
+        }
+        if (req.message === INPUT_MSG) {
+            data = res.content;
+        }
+    }
+    return {
+        earlyResponse: undefined,
+        data,
+    };
+}
+/**
+ * Converts elicit response action into appropriate MCP result
+ * @param elicitResponse - Result from MCP server elicit input call
+ * @returns MCP result for decline/cancel actions, undefined for accept
+ * @throws Error if invalid response action is received
+ */
+function handleElicitResponse(elicitResponse) {
+    switch (elicitResponse.action) {
+        case "accept":
+            return undefined;
+        case "decline":
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Action was declined.",
+                    },
+                ],
+            };
+        case "cancel":
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Action was cancelled",
+                    },
+                ],
+            };
+        default:
+            throw new Error("Invalid elicit response received");
+    }
+}
+/**
+ * Determines the schema type for elicit input based on Zod parameter type
+ * @param param - Zod schema parameter to analyze
+ * @returns Corresponding elicit schema type string
+ * @throws Error if parameter type is not supported for elicitation
+ */
+function determineSchemaType(param) {
+    if (param instanceof zod_1.z.ZodBoolean) {
+        return "boolean";
+    }
+    else if (param instanceof zod_1.z.ZodString) {
+        return "string";
+    }
+    else if (param instanceof zod_1.z.ZodNumber) {
+        return "number";
+    }
+    throw new Error("Unsupported elicitation input type");
+}
+/**
+ * Constructs confirmation elicit request for tool execution
+ * @param model - MCP annotation model containing tool description
+ * @returns Elicit request parameters for user confirmation
+ */
+function contructElicitConfirm(model) {
+    return {
+        message: `Please confirm that you want to perform action '${model.description}'`,
+        requestedSchema: {
+            type: "object",
+            properties: {
+                confirm: {
+                    type: "boolean",
+                    title: "Confirmation",
+                    description: "Please confirm the action",
+                },
+            },
+            required: ["confirm"],
+        },
+    };
+}
+/**
+ * Constructs input elicit request for tool parameters
+ * @param params - Tool parameters definition with Zod schemas
+ * @returns Elicit request parameters for user input collection
+ */
+function constructElicitInput(params) {
+    const elicitSpec = {
+        message: INPUT_MSG,
+        requestedSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    };
+    for (const [key, zodType] of Object.entries(params)) {
+        elicitSpec.requestedSchema.required?.push(key);
+        elicitSpec.requestedSchema.properties[key] = {
+            type: determineSchemaType(zodType),
+            title: key,
+            description: key,
+        };
+    }
+    return elicitSpec;
+}

package/lib/mcp/tools.js

@@ -6,6 +6,7 @@ const logger_1 = require("../logger");
 const constants_1 = require("./constants");
 const zod_1 = require("zod");
 const utils_2 = require("../auth/utils");
+const elicited_input_1 = require("./elicited-input");
 /* @ts-ignore */
 const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
 /**
@@ -37,7 +38,12 @@ function assignBoundOperation(params, model, server, authEnabled) {
         throw new Error("Bound operation cannot be assigned to tool list, missing keys");
     }
     const keys = buildToolParameters(model.keyTypeMap);
-    const inputSchema = buildZodSchema({ ...keys, ...params });
+    const useElicitInput = (0, elicited_input_1.isElicitInput)(model.elicits);
+    const inputSchema = buildZodSchema({
+        ...keys,
+        ...(useElicitInput ? {} : params),
+    });
+    const elicitationRequests = (0, elicited_input_1.constructElicitationFunctions)(model, params);
     server.registerTool(model.name, {
         title: model.name,
         description: model.description,
@@ -69,11 +75,15 @@ function assignBoundOperation(params, model, server, authEnabled) {
                 continue;
             operationInput[k] = v;
         }
+        const elicitationResult = await (0, elicited_input_1.handleElicitationRequests)(elicitationRequests, server);
+        if (elicitationResult?.earlyResponse) {
+            return elicitationResult.earlyResponse;
+        }
         const accessRights = (0, utils_2.getAccessRights)(authEnabled);
         const response = await service.tx({ user: accessRights }).send({
             event: model.target,
             entity: model.entityKey,
-            data: operationInput,
+            data: elicitationResult?.data ?? operationInput,
             params: [operationKeys],
         });
         return (0, utils_1.asMcpResult)(response);
@@ -87,7 +97,9 @@ function assignBoundOperation(params, model, server, authEnabled) {
  * @param server - MCP server instance to register with
  */
 function assignUnboundOperation(params, model, server, authEnabled) {
-    const inputSchema = buildZodSchema(params);
+    const useElicitInput = (0, elicited_input_1.isElicitInput)(model.elicits);
+    const inputSchema = buildZodSchema(useElicitInput ? {} : params);
+    const elicitationRequests = (0, elicited_input_1.constructElicitationFunctions)(model, params);
     server.registerTool(model.name, {
         title: model.name,
         description: model.description,
@@ -109,10 +121,14 @@ function assignUnboundOperation(params, model, server, authEnabled) {
                 ],
             };
         }
+        const elicitationResult = await (0, elicited_input_1.handleElicitationRequests)(elicitationRequests, server);
+        if (elicitationResult?.earlyResponse) {
+            return elicitationResult.earlyResponse;
+        }
         const accessRights = (0, utils_2.getAccessRights)(authEnabled);
         const response = await service
             .tx({ user: accessRights })
-            .send(model.target, args);
+            .send(model.target, elicitationResult?.data ?? args);
         return (0, utils_1.asMcpResult)(response);
     });
 }
@@ -130,27 +146,6 @@ function buildToolParameters(params) {
     }
     return result;
 }
-/**
- * Converts a value to a string representation suitable for MCP responses
- * Handles objects and arrays by JSON stringifying them instead of using String()
- * @param value - The value to convert to string
- * @returns String representation of the value
- */
-function formatResponseValue(value) {
-    if (value === null || value === undefined) {
-        return String(value);
-    }
-    if (typeof value === "object") {
-        try {
-            return JSON.stringify(value, null, 2);
-        }
-        catch (error) {
-            // Fallback to String() if JSON.stringify fails (e.g., circular references)
-            return String(value);
-        }
-    }
-    return String(value);
-}
 /**
  * Constructs a complete Zod schema object for MCP tool input validation
  * @param params - Record of parameter names to Zod schema types

package/lib/mcp/utils.js

@@ -18,6 +18,8 @@ function determineMcpParameterType(cdsType) {
             return zod_1.z.string();
         case "Integer":
             return zod_1.z.number();
+        case "Boolean":
+            return zod_1.z.boolean();
         default:
             return zod_1.z.string();
     }

package/package.json

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