@gavdi/cap-mcp 1.6.0 → 1.8.0

package/README.md

@@ -294,6 +294,40 @@ extend projection Books with actions {
 }
 ```
 
+#### Required vs Optional Parameters
+
+Parameters follow standard CDS nullability rules. A parameter declared `not null` is **required** in the MCP tool schema; a parameter without `not null` is **optional** and may be omitted by the AI agent.
+
+```cds
+@mcp: {
+  name       : 'search-items',
+  description: 'Search for items by keyword with optional filters',
+  tool       : true
+}
+function searchItems(
+  query    : String  not null,  // required — must be provided
+  category : String,            // optional — may be omitted
+  limit    : Integer,           // optional — may be omitted
+  format   : String             // optional — may be omitted
+) returns array of String;
+```
+
+The generated JSON Schema will list only `not null` parameters in the `required` array:
+
+```json
+{
+  "properties": {
+    "query":    { "type": "string" },
+    "category": { "type": "string" },
+    "limit":    { "type": "integer" },
+    "format":   { "type": "string" }
+  },
+  "required": ["query"]
+}
+```
+
+> **Note:** This behaviour applies to unbound functions and actions. Entity wrapper tools (`query`, `get`, `create`, `update`) derive nullability from the entity element definitions.
+
 #### Tool Elicitation
 
 Request user confirmation or input before tool execution using the `elicit` property:

package/lib/annotations/utils.js

@@ -236,7 +236,8 @@ function parseOperationElements(annotations, model) {
                 }
                 continue;
             }
-            parseParam(k, v);
+            const optionalSuffix = v.notNull ? undefined : "Optional";
+            parseParam(k, v, optionalSuffix);
         }
     }
     return {

package/lib/mcp/entity-tools.js

@@ -358,7 +358,16 @@ function registerQueryTool(resAnno, server, authEnabled) {
             return (0, utils_2.toolError)("QUERY_FAILED", msg);
         }
     };
-    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, queryHandler);
+    server.registerTool(toolName, {
+        title: toolName,
+        description: desc,
+        inputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, queryHandler);
 }
 /**
  * Registers the get-by-keys tool for an entity.
@@ -429,7 +438,16 @@ function registerGetTool(resAnno, server, authEnabled) {
             return (0, utils_2.toolError)("GET_FAILED", msg);
         }
     };
-    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, getHandler);
+    server.registerTool(toolName, {
+        title: toolName,
+        description: desc,
+        inputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, getHandler);
 }
 /**
  * Registers the create tool for an entity.
@@ -528,7 +546,16 @@ function registerCreateTool(resAnno, server, authEnabled) {
             return (0, utils_2.toolError)(isTimeout ? "TIMEOUT" : "CREATE_FAILED", msg);
         }
     };
-    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, createHandler);
+    server.registerTool(toolName, {
+        title: toolName,
+        description: desc,
+        inputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+    }, createHandler);
 }
 /**
  * Registers the update tool for an entity.
@@ -647,7 +674,16 @@ function registerUpdateTool(resAnno, server, authEnabled) {
             return (0, utils_2.toolError)(isTimeout ? "TIMEOUT" : "UPDATE_FAILED", msg);
         }
     };
-    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, updateHandler);
+    server.registerTool(toolName, {
+        title: toolName,
+        description: desc,
+        inputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, updateHandler);
 }
 /**
  * Registers the delete tool for an entity.
@@ -716,7 +752,16 @@ function registerDeleteTool(resAnno, server, authEnabled) {
             return (0, utils_2.toolError)(isTimeout ? "TIMEOUT" : "DELETE_FAILED", msg);
         }
     };
-    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, deleteHandler);
+    server.registerTool(toolName, {
+        title: toolName,
+        description: desc,
+        inputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
+    }, deleteHandler);
 }
 // Helper: compile structured inputs into a CDS query
 // The function translates the validated MCP input into CQN safely,

package/lib/mcp/tools.js

@@ -25,6 +25,26 @@ function assignToolToServer(model, server, authEnabled) {
     }
     assignUnboundOperation(parameters, model, server, authEnabled);
 }
+/**
+ * Derives MCP tool behaviour hints from a CDS operation kind.
+ *
+ * CDS `function`s are non-side-effecting reads, while `action`s are
+ * side-effecting writes. These map onto the MCP `ToolAnnotations` hints so
+ * clients can advertise read-only/destructive intent in `tools/list`.
+ *
+ * Any non-`function` kind (including an undefined kind) is treated as an
+ * action to stay on the safe, write-capable side.
+ * @param model - The tool annotation carrying the parsed operation kind
+ * @returns Tool annotation hints describing the operation's behaviour
+ */
+function buildOperationAnnotations(model) {
+    const readOnly = model.operationKind === "function";
+    return {
+        readOnlyHint: readOnly,
+        destructiveHint: !readOnly,
+        idempotentHint: readOnly,
+    };
+}
 /**
  * Registers a bound operation that operates on a specific entity instance
  * Requires entity key parameters in addition to operation parameters
@@ -48,6 +68,7 @@ function assignBoundOperation(params, model, server, authEnabled) {
         title: model.name,
         description: model.description,
         inputSchema: inputSchema,
+        annotations: buildOperationAnnotations(model),
     }, async (args) => {
         // Resolve from current CAP context; prefer global to align with Jest mocks
         const cdsMod = global.cds || cds;
@@ -104,6 +125,7 @@ function assignUnboundOperation(params, model, server, authEnabled) {
         title: model.name,
         description: model.description,
         inputSchema: inputSchema,
+        annotations: buildOperationAnnotations(model),
     }, async (args) => {
         // Resolve from current CAP context; prefer global to align with Jest mocks
         const cdsMod = global.cds || cds;

package/lib/mcp/utils.js

@@ -17,6 +17,10 @@ const cds = global.cds || require("@sap/cds"); // This is a work around for miss
  * @returns Zod schema instance for the given type
  */
 function determineMcpParameterType(cdsType, key, target) {
+    if (cdsType?.endsWith("Optional")) {
+        const baseType = cdsType.slice(0, -"Optional".length);
+        return determineMcpParameterType(baseType, key, target).optional();
+    }
     switch (cdsType) {
         case "String":
             return zod_1.z.string();

package/lib/mcp.js

@@ -57,6 +57,12 @@ class McpPlugin {
                 },
             },
         }));
+        // Apply body limit
+        const limit = cds.env.mcp?.body_parser?.limit ??
+            cds.env.server?.body_parser?.limit ??
+            "100kb"; // preserve current default if no config
+        this.expressApp.use("/mcp", express_1.default.json({ limit }));
+        // Handle auth configuration
         if (this.config.auth === "inherit") {
             (0, utils_2.registerAuthMiddleware)(this.expressApp);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavdi/cap-mcp",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "MCP Plugin for CAP",
   "keywords": [
     "MCP",
@@ -43,24 +43,24 @@
     "docs:links": "markdown-link-check docs/**/*.md"
   },
   "peerDependencies": {
-    "@sap/cds": ">=9",
+    "@sap/cds": ">=10",
     "express": "^5"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.23.0",
-    "@sap/xssec": "^4.9.1",
+    "@sap/xssec": "^4.13.3",
     "cors": "^2.8.5",
     "helmet": "^8.1.0",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5"
   },
   "devDependencies": {
-    "@cap-js/cds-types": "^0.13.0",
-    "@release-it/conventional-changelog": "^10.0.1",
+    "@cap-js/cds-types": "^0.18.0",
+    "@release-it/conventional-changelog": "^11.0.1",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.3.0",
+    "@types/node": "^26.1.1",
     "@types/sinon": "^17.0.4",
     "@types/supertest": "^6.0.2",
     "docsify-cli": "^4.4.4",
@@ -70,7 +70,7 @@
     "lint-staged": "^16.1.2",
     "markdown-link-check": "^3.14.1",
     "prettier": "^3.5.3",
-    "release-it": "^19.0.4",
+    "release-it": "^20.2.1",
     "sinon": "^21.0.0",
     "supertest": "^7.0.0",
     "ts-jest": "^29.4.0",