@gavdi/cap-mcp 0.9.7 → 0.9.8

package/README.md

@@ -62,7 +62,8 @@ Add MCP configuration to your `package.json`:
       "name": "my-bookshop-mcp",
       "auth": "inherit",
       "wrap_entities_to_actions": false,
-      "wrap_entity_modes": ["query", "get"]
+      "wrap_entity_modes": ["query", "get"],
+      "instructions": "MCP server instructions for agents"
     }
   }
 }
@@ -251,6 +252,7 @@ Configure the MCP plugin through your CAP application's `package.json` or `.cdsr
       "name": "my-mcp-server",
       "version": "1.0.0",
       "auth": "inherit",
+      "instructions": "mcp server instructions for agents",
       "capabilities": {
         "resources": {
           "listChanged": true,

package/lib/annotations/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ALL_RESOURCE_OPTIONS = exports.MCP_ANNOTATION_PROPS = exports.MCP_ANNOTATION_KEY = void 0;
+exports.DEFAULT_ALL_RESOURCE_OPTIONS = exports.CDS_AUTH_ANNOTATIONS = exports.MCP_ANNOTATION_PROPS = exports.MCP_ANNOTATION_KEY = void 0;
 /**
  * MCP annotation constants and default configurations
  * Defines the standard annotation keys and default values used throughout the plugin
@@ -28,6 +28,14 @@ exports.MCP_ANNOTATION_PROPS = {
     /** Wrapper configuration for exposing entities as tools */
     MCP_WRAP: "@mcp.wrap",
 };
+/**
+ * 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",
+};
 /**
  * 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

@@ -70,8 +70,12 @@ function parseAnnotations(definition) {
         definition: definition,
     };
     for (const [k, v] of Object.entries(definition)) {
-        if (!k.includes(constants_1.MCP_ANNOTATION_KEY))
+        // 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:
@@ -93,6 +97,12 @@ function parseAnnotations(definition) {
                 // Wrapper container to expose resources as tools
                 annotations.wrap = 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;
         }
@@ -112,7 +122,8 @@ function constructResourceAnnotation(serviceName, target, annotations, definitio
         return undefined;
     const functionalities = (0, utils_1.determineResourceOptions)(annotations);
     const { properties, resourceKeys } = (0, utils_1.parseResourceElements)(definition);
-    return new structures_1.McpResourceAnnotation(annotations.name, annotations.description, target, serviceName, functionalities, properties, resourceKeys, annotations.wrap);
+    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);
 }
 /**
  * Constructs a tool annotation from parsed annotation data
@@ -127,7 +138,8 @@ function constructToolAnnotation(serviceName, target, annotations, entityKey, ke
     if (!(0, utils_1.isValidToolAnnotation)(annotations))
         return undefined;
     const { parameters, operationKind } = (0, utils_1.parseOperationElements)(annotations);
-    return new structures_1.McpToolAnnotation(annotations.name, annotations.description, target, serviceName, parameters, entityKey, operationKind, keyParams);
+    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);
 }
 /**
  * Constructs a prompt annotation from parsed annotation data

package/lib/annotations/structures.js

@@ -14,18 +14,22 @@ class McpAnnotation {
     _target;
     /** The name of the CAP service this annotation belongs to */
     _serviceName;
+    /** Auth roles by providing CDS that is required for use */
+    _restrictions;
     /**
      * Creates a new MCP annotation instance
      * @param name - Unique identifier for this annotation
      * @param description - Human-readable description
      * @param target - The target element this annotation applies to
      * @param serviceName - Name of the associated CAP service
+     * @param restrictions - Roles required for the given annotation
      */
-    constructor(name, description, target, serviceName) {
+    constructor(name, description, target, serviceName, restrictions) {
         this._name = name;
         this._description = description;
         this._target = target;
         this._serviceName = serviceName;
+        this._restrictions = restrictions;
     }
     /**
      * Gets the unique name identifier for this annotation
@@ -55,6 +59,14 @@ class McpAnnotation {
     get serviceName() {
         return this._serviceName;
     }
+    /**
+     * Gets the list of roles required for access to the annotation.
+     * If the list is empty, then all can access.
+     * @returns List of required roles
+     */
+    get restrictions() {
+        return this._restrictions;
+    }
 }
 exports.McpAnnotation = McpAnnotation;
 /**
@@ -79,9 +91,10 @@ 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 restrictions - Optional restrictions based on CDS roles
      */
-    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys, wrap) {
-        super(name, description, target, serviceName);
+    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys, wrap, restrictions) {
+        super(name, description, target, serviceName, restrictions ?? []);
         this._functionalities = functionalities;
         this._properties = properties;
         this._resourceKeys = resourceKeys;
@@ -139,9 +152,10 @@ class McpToolAnnotation extends McpAnnotation {
      * @param entityKey - Optional entity key field for bound operations
      * @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
      */
-    constructor(name, description, operation, serviceName, parameters, entityKey, operationKind, keyTypeMap) {
-        super(name, description, operation, serviceName);
+    constructor(name, description, operation, serviceName, parameters, entityKey, operationKind, keyTypeMap, restrictions) {
+        super(name, description, operation, serviceName, restrictions ?? []);
         this._parameters = parameters;
         this._entityKey = entityKey;
         this._operationKind = operationKind;
@@ -192,7 +206,7 @@ class McpPromptAnnotation extends McpAnnotation {
      * @param prompts - Array of prompt template definitions
      */
     constructor(name, description, serviceName, prompts) {
-        super(name, description, serviceName, serviceName);
+        super(name, description, serviceName, serviceName, []);
         this._prompts = prompts;
     }
     /**

package/lib/annotations/utils.js

@@ -10,6 +10,7 @@ exports.determineResourceOptions = determineResourceOptions;
 exports.parseResourceElements = parseResourceElements;
 exports.parseOperationElements = parseOperationElements;
 exports.parseEntityKeys = parseEntityKeys;
+exports.parseCdsRestrictions = parseCdsRestrictions;
 const constants_1 = require("./constants");
 const logger_1 = require("../logger");
 /**
@@ -191,3 +192,64 @@ function parseEntityKeys(definition) {
     }
     return result;
 }
+/**
+ * Parses the CDS role restrictions to be used for MCP
+ */
+function parseCdsRestrictions(restrictions, requires) {
+    if (!restrictions && !requires)
+        return [];
+    const result = [];
+    if (requires) {
+        result.push({
+            role: requires,
+        });
+    }
+    if (!restrictions || restrictions.length <= 0)
+        return result;
+    for (const el of restrictions) {
+        const ops = mapOperationRestriction(el.grant);
+        if (!el.to) {
+            result.push({
+                role: "authenticated-user",
+                operations: ops,
+            });
+            continue;
+        }
+        const mapped = el.to.map((to) => ({
+            role: to,
+            operations: ops,
+        }));
+        result.push(...mapped);
+    }
+    return result;
+}
+/**
+ * Maps the "grant" property from CdsRestriction to McpRestriction
+ */
+function mapOperationRestriction(cdsRestrictions) {
+    const result = [];
+    if (!cdsRestrictions || cdsRestrictions.length <= 0) {
+        result.push("CREATE");
+        result.push("READ");
+        result.push("UPDATE");
+        result.push("DELETE");
+        return result;
+    }
+    for (const el of cdsRestrictions) {
+        switch (el) {
+            case "CHANGE":
+                result.push("UPDATE");
+                continue;
+            case "*":
+                result.push("CREATE");
+                result.push("READ");
+                result.push("UPDATE");
+                result.push("DELETE");
+                continue;
+            default:
+                result.push(el);
+                continue;
+        }
+    }
+    return result;
+}

package/lib/auth/utils.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAuthEnabled = isAuthEnabled;
 exports.getAccessRights = getAccessRights;
 exports.registerAuthMiddleware = registerAuthMiddleware;
+exports.hasToolOperationAccess = hasToolOperationAccess;
+exports.getWrapAccesses = getWrapAccesses;
 const handler_1 = require("./handler");
 const proxyProvider_js_1 = require("@modelcontextprotocol/sdk/server/auth/providers/proxyProvider.js");
 const router_js_1 = require("@modelcontextprotocol/sdk/server/auth/router.js");
@@ -210,3 +212,61 @@ function configureOAuthProxy(expressApp) {
         serviceDocumentationUrl: new URL("https://docs.cloudfoundry.org/api/uaa/version/77.34.0/index.html#authorization"),
     }));
 }
+/**
+ * Checks whether the requesting user's access matches that of the roles required
+ * @param user
+ * @returns true if the user has access
+ */
+function hasToolOperationAccess(user, roles) {
+    // If no restrictions are defined, allow access
+    if (!roles || roles.length === 0)
+        return true;
+    for (const el of roles) {
+        if (user.is(el.role))
+            return true;
+    }
+    return false;
+}
+/**
+ * Determines wrap accesses based on the given MCP restrictions derived from annotations
+ * @param user
+ * @param restrictions
+ * @returns wrap tool accesses
+ */
+function getWrapAccesses(user, restrictions) {
+    // If no restrictions are defined, allow all access
+    if (!restrictions || restrictions.length === 0) {
+        return {
+            canRead: true,
+            canCreate: true,
+            canUpdate: true,
+            canDelete: true,
+        };
+    }
+    const access = {};
+    for (const el of restrictions) {
+        // If the user does not even have the role then no reason to check
+        if (!user.is(el.role))
+            continue;
+        if (!el.operations || el.operations.length <= 0) {
+            access.canRead = true;
+            access.canCreate = true;
+            access.canDelete = true;
+            access.canUpdate = true;
+            break;
+        }
+        if (el.operations.includes("READ")) {
+            access.canRead = true;
+        }
+        if (el.operations.includes("UPDATE")) {
+            access.canUpdate = true;
+        }
+        if (el.operations.includes("CREATE")) {
+            access.canCreate = true;
+        }
+        if (el.operations.includes("DELETE")) {
+            access.canDelete = true;
+        }
+    }
+    return access;
+}

package/lib/config/loader.js

@@ -35,6 +35,7 @@ function loadConfiguration() {
             "create",
             "update",
         ],
+        instructions: cdsEnv?.instructions,
     };
 }
 /**

package/lib/mcp/entity-tools.js

@@ -66,28 +66,36 @@ const TIMEOUT_MS = 10_000; // Standard timeout for tool calls (ms)
  * Modes can be controlled globally via configuration and per-entity via @mcp.wrap.
  *
  * Example tool names (naming is explicit for easier LLM usage):
- *   Service_Entity_query, Service_Entity_get, Service_Entity_create, Service_Entity_update
+ *   Service_Entity_query, Service_Entity_get, Service_Entity_create, Service_Entity_update, Service_Entity_delete
  */
-function registerEntityWrappers(resAnno, server, authEnabled, defaultModes) {
+function registerEntityWrappers(resAnno, server, authEnabled, defaultModes, accesses) {
     const CDS = global.cds;
     logger_1.LOGGER.debug(`[REGISTRATION TIME] Registering entity wrappers for ${resAnno.serviceName}.${resAnno.target}, available services:`, Object.keys(CDS.services || {}));
     const modes = resAnno.wrap?.modes ?? defaultModes;
-    if (modes.includes("query")) {
+    if (modes.includes("query") && accesses.canRead) {
         registerQueryTool(resAnno, server, authEnabled);
     }
     if (modes.includes("get") &&
         resAnno.resourceKeys &&
-        resAnno.resourceKeys.size > 0) {
+        resAnno.resourceKeys.size > 0 &&
+        accesses.canRead) {
         registerGetTool(resAnno, server, authEnabled);
     }
-    if (modes.includes("create")) {
+    if (modes.includes("create") && accesses.canCreate) {
         registerCreateTool(resAnno, server, authEnabled);
     }
     if (modes.includes("update") &&
         resAnno.resourceKeys &&
-        resAnno.resourceKeys.size > 0) {
+        resAnno.resourceKeys.size > 0 &&
+        accesses.canUpdate) {
         registerUpdateTool(resAnno, server, authEnabled);
     }
+    if (modes.includes("delete") &&
+        resAnno.resourceKeys &&
+        resAnno.resourceKeys.size > 0 &&
+        accesses.canDelete) {
+        registerDeleteTool(resAnno, server, authEnabled);
+    }
 }
 /**
  * Builds the visible tool name for a given operation mode.
@@ -474,6 +482,78 @@ function registerUpdateTool(resAnno, server, authEnabled) {
     };
     server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, updateHandler);
 }
+/**
+ * Registers the delete tool for an entity.
+ * Requires keys to identify the entity to delete.
+ */
+function registerDeleteTool(resAnno, server, authEnabled) {
+    const toolName = nameFor(resAnno.serviceName, resAnno.target, "delete");
+    const inputSchema = {};
+    // Keys required for deletion
+    for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
+        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 deleteHandler = async (args) => {
+        const CDS = global.cds;
+        const { DELETE } = CDS.ql;
+        const svc = await resolveServiceInstance(resAnno.serviceName);
+        if (!svc) {
+            const msg = `Service not found: ${resAnno.serviceName}. Available: ${Object.keys(CDS.services || {}).join(", ")}`;
+            logger_1.LOGGER.error(msg);
+            return (0, utils_2.toolError)("ERR_MISSING_SERVICE", msg);
+        }
+        // Extract keys - similar to get/update handlers
+        const keys = {};
+        for (const [k] of resAnno.resourceKeys.entries()) {
+            let provided = args[k];
+            if (provided === undefined) {
+                // Case-insensitive key matching (like in get handler)
+                const alt = Object.entries(args || {}).find(([kk]) => String(kk).toLowerCase() === String(k).toLowerCase());
+                if (alt)
+                    provided = args[alt[0]];
+            }
+            if (provided === undefined) {
+                logger_1.LOGGER.warn(`Delete tool missing required key`, { key: k, toolName });
+                return (0, utils_2.toolError)("MISSING_KEY", `Missing key '${k}'`);
+            }
+            // Coerce numeric strings (like in get handler)
+            const raw = provided;
+            keys[k] =
+                typeof raw === "string" && /^\d+$/.test(raw) ? Number(raw) : raw;
+        }
+        logger_1.LOGGER.debug(`Executing DELETE on ${resAnno.target} with keys`, keys);
+        const tx = svc.tx({ user: (0, utils_1.getAccessRights)(authEnabled) });
+        try {
+            const response = await withTimeout(tx.run(DELETE.from(resAnno.target).where(keys)), TIMEOUT_MS, toolName, async () => {
+                try {
+                    await tx.rollback();
+                }
+                catch { }
+            });
+            try {
+                await tx.commit();
+            }
+            catch { }
+            return (0, utils_2.asMcpResult)(response ?? { deleted: true });
+        }
+        catch (error) {
+            try {
+                await tx.rollback();
+            }
+            catch { }
+            const isTimeout = String(error?.message || "").includes("timed out");
+            const msg = isTimeout
+                ? `${toolName} timed out after ${TIMEOUT_MS}ms`
+                : `DELETE_FAILED: ${error?.message || String(error)}`;
+            logger_1.LOGGER.error(msg, error);
+            return (0, utils_2.toolError)(isTimeout ? "TIMEOUT" : "DELETE_FAILED", msg);
+        }
+    };
+    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, deleteHandler);
+}
 // Helper: compile structured inputs into a CDS query
 // The function translates the validated MCP input into CQN safely,
 // including a basic escape of string literals to avoid invalid syntax.

package/lib/mcp/factory.js

@@ -24,7 +24,7 @@ function createMcpServer(config, annotations) {
         name: config.name,
         version: config.version,
         capabilities: config.capabilities,
-    });
+    }, { instructions: config.instructions });
     if (!annotations) {
         logger_1.LOGGER.debug("No annotations provided, skipping registration...");
         return server;
@@ -33,20 +33,26 @@ function createMcpServer(config, annotations) {
     const authEnabled = (0, utils_1.isAuthEnabled)(config.auth);
     // Always register discovery tool for better model planning
     (0, describe_model_1.registerDescribeModelTool)(server);
+    const accessRights = (0, utils_1.getAccessRights)(authEnabled);
     for (const entry of annotations.values()) {
         if (entry instanceof structures_1.McpToolAnnotation) {
+            if (!(0, utils_1.hasToolOperationAccess)(accessRights, entry.restrictions))
+                continue;
             (0, tools_1.assignToolToServer)(entry, server, authEnabled);
             continue;
         }
         else if (entry instanceof structures_1.McpResourceAnnotation) {
-            (0, resources_1.assignResourceToServer)(entry, server, authEnabled);
+            const accesses = (0, utils_1.getWrapAccesses)(accessRights, entry.restrictions);
+            if (accesses.canRead) {
+                (0, resources_1.assignResourceToServer)(entry, server, authEnabled);
+            }
             // Optionally expose entities as tools based on global/per-entity switches
             const globalWrap = !!config.wrap_entities_to_actions;
             const localWrap = entry.wrap?.tools;
             const enabled = localWrap === true || (localWrap === undefined && globalWrap);
             if (enabled) {
                 const modes = config.wrap_entity_modes ?? ["query", "get"];
-                (0, entity_tools_1.registerEntityWrappers)(entry, server, authEnabled, modes);
+                (0, entity_tools_1.registerEntityWrappers)(entry, server, authEnabled, modes, accesses);
             }
             continue;
         }

package/lib/mcp.js

@@ -39,7 +39,7 @@ class McpPlugin {
     async onBootstrap(app) {
         logger_1.LOGGER.debug("Event received for 'bootstrap'");
         this.expressApp = app;
-        this.expressApp.use(express_1.default.json());
+        this.expressApp.use("/mcp", express_1.default.json());
         if (this.config.auth === "inherit") {
             (0, utils_2.registerAuthMiddleware)(this.expressApp);
         }

package/package.json

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