@gavdi/cap-mcp 0.9.4 → 0.9.8

package/README.md

@@ -60,7 +60,10 @@ Add MCP configuration to your `package.json`:
   "cds": {
     "mcp": {
       "name": "my-bookshop-mcp",
-      "auth": "inherit"
+      "auth": "inherit",
+      "wrap_entities_to_actions": false,
+      "wrap_entity_modes": ["query", "get"],
+      "instructions": "MCP server instructions for agents"
     }
   }
 }
@@ -80,6 +83,13 @@ service CatalogService {
     resource: ['filter', 'orderby', 'select', 'top', 'skip']
   }
   entity Books as projection on my.Books;
+  
+  // Optionally expose Books as tools for LLMs (query/get enabled by default config)
+  annotate CatalogService.Books with @mcp.wrap: {
+    tools: true,
+    modes: ['query','get'],
+    hint: 'Use for read-only lookups of books'
+  };
 
   @mcp: {
     name: 'get-book-recommendations',
@@ -114,10 +124,32 @@ This plugin transforms your annotated CAP services into a fully functional MCP s
 
 - **📊 Resources**: Expose CAP entities as MCP resources with OData v4 query capabilities
 - **🔧 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
 - **🔄 Auto-generation**: Automatically creates MCP server endpoints based on annotations
 - **⚙️ Flexible Configuration**: Support for custom parameter sets and descriptions
 
+## 🧪 Testing & Inspector
+
+- Run tests: `npm test`
+- Start demo app: `npm run mock`
+- Inspector: `npx @modelcontextprotocol/inspector`
+
+### New wrapper tools
+
+When `wrap_entities_to_actions` is enabled (globally or via `@mcp.wrap.tools: true`), you will see tools named like:
+
+- `CatalogService_Books_query`
+- `CatalogService_Books_get`
+- `CatalogService_Books_create` (if enabled)
+- `CatalogService_Books_update` (if enabled)
+
+Each tool includes a description with fields and OData notes to guide the model. You can add `@mcp.wrap.hint` per entity to enrich descriptions for LLMs.
+
+### Bruno collection
+
+The `bruno/` folder contains HTTP requests for the MCP endpoint (handy for local manual testing using Bruno or any HTTP client). You may add calls for `tools/list` and `tools/call` to exercise the new wrapper tools.
+
 ## 📝 Usage
 
 ### Resource Annotations
@@ -220,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,
@@ -425,6 +458,10 @@ npm test -- --verbose
 npm test -- --watch
 ```
 
+### Further reading
+
+- Short guide on entity tools and configuration: `docs/entity-tools.md`
+
 ## 🤝 Contributing
 
 Contributions are welcome! This is an open-source project aimed at bridging CAP applications with the AI ecosystem.

package/cds-plugin.js

@@ -1,4 +1,4 @@
-const cds = global.cds || require("@sap/cds");
+const cds = global.cds; // enforce host app cds instance
 const McpPlugin = require("./lib/mcp").default;
 
 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.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
@@ -25,6 +25,16 @@ exports.MCP_ANNOTATION_PROPS = {
     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",
+};
+/**
+ * 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

package/lib/annotations/parser.js

@@ -18,16 +18,18 @@ function parseDefinitions(model) {
     }
     const result = new Map();
     for (const [key, value] of Object.entries(model.definitions)) {
-        const parsedAnnotations = parseAnnotations(value);
+        // Narrow unknown to csn.Definition with a runtime check
+        const def = value;
+        const parsedAnnotations = parseAnnotations(def);
         const { serviceName, target } = (0, utils_1.splitDefinitionName)(key);
-        parseBoundOperations(serviceName, target, value, result); // Mutates result map with bound operations
+        parseBoundOperations(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
         }
         const verifiedAnnotations = parsedAnnotations;
-        switch (value.kind) {
+        switch (def.kind) {
             case "entity":
-                const resourceAnnotation = constructResourceAnnotation(serviceName, target, verifiedAnnotations, value);
+                const resourceAnnotation = constructResourceAnnotation(serviceName, target, verifiedAnnotations, def);
                 if (!resourceAnnotation)
                     continue;
                 result.set(resourceAnnotation.target, resourceAnnotation);
@@ -68,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:
@@ -87,6 +93,16 @@ function parseAnnotations(definition) {
             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.CDS_AUTH_ANNOTATIONS.REQUIRES:
+                annotations.requires = v;
+                continue;
+            case constants_1.CDS_AUTH_ANNOTATIONS.RESTRICT:
+                annotations.restrict = v;
+                continue;
             default:
                 continue;
         }
@@ -106,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);
+    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
@@ -121,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;
 /**
@@ -68,6 +80,8 @@ class McpResourceAnnotation extends McpAnnotation {
     _properties;
     /** Map of resource key fields to their types */
     _resourceKeys;
+    /** Optional wrapper configuration to expose this resource as tools */
+    _wrap;
     /**
      * Creates a new MCP resource annotation
      * @param name - Unique identifier for this resource
@@ -77,12 +91,14 @@ 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) {
-        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;
+        this._wrap = wrap;
     }
     /**
      * Gets the set of enabled OData query functionalities
@@ -105,6 +121,12 @@ class McpResourceAnnotation extends McpAnnotation {
     get resourceKeys() {
         return this._resourceKeys;
     }
+    /**
+     * Gets the wrapper configuration for exposing this resource as tools
+     */
+    get wrap() {
+        return this._wrap;
+    }
 }
 exports.McpResourceAnnotation = McpResourceAnnotation;
 /**
@@ -130,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;
@@ -183,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

@@ -28,6 +28,14 @@ function loadConfiguration() {
             resources: cdsEnv?.capabilities?.resources ?? { listChanged: true },
             prompts: cdsEnv?.capabilities?.prompts ?? { listChanged: true },
         },
+        wrap_entities_to_actions: cdsEnv?.wrap_entities_to_actions ?? false,
+        wrap_entity_modes: cdsEnv?.wrap_entity_modes ?? [
+            "query",
+            "get",
+            "create",
+            "update",
+        ],
+        instructions: cdsEnv?.instructions,
     };
 }
 /**

package/lib/logger.js

@@ -7,8 +7,54 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LOGGER = void 0;
 /* @ts-ignore */
 const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
+// In some test/mocked environments cds.log may not exist. Provide a no-op fallback.
+const safeLog = (ns) => {
+    try {
+        if (typeof cds?.log === "function")
+            return cds.log(ns);
+    }
+    catch { }
+    return {
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+    };
+};
+// Create both channels so logs show up even if the app configured "mcp" instead of "cds-mcp"
+const loggerPrimary = safeLog("cds-mcp");
+const loggerCompat = safeLog("mcp");
 /**
  * Shared logger instance for all MCP plugin components
- * Provides debug, info, warn, and error logging methods
+ * Multiplexes logs to both "cds-mcp" and legacy "mcp" channels for visibility
  */
-exports.LOGGER = cds.log("cds-mcp");
+exports.LOGGER = {
+    debug: (...args) => {
+        try {
+            loggerPrimary?.debug?.(...args);
+            loggerCompat?.debug?.(...args);
+        }
+        catch { }
+    },
+    info: (...args) => {
+        try {
+            loggerPrimary?.info?.(...args);
+            loggerCompat?.info?.(...args);
+        }
+        catch { }
+    },
+    warn: (...args) => {
+        try {
+            loggerPrimary?.warn?.(...args);
+            loggerCompat?.warn?.(...args);
+        }
+        catch { }
+    },
+    error: (...args) => {
+        try {
+            loggerPrimary?.error?.(...args);
+            loggerCompat?.error?.(...args);
+        }
+        catch { }
+    },
+};

package/lib/mcp/describe-model.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDescribeModelTool = registerDescribeModelTool;
+const utils_1 = require("./utils");
+const zod_1 = require("zod");
+/**
+ * Registers a discovery tool that describes CAP services/entities and fields.
+ * Helpful for models to plan correct tool calls without trial-and-error.
+ */
+function registerDescribeModelTool(server) {
+    const inputZod = zod_1.z
+        .object({
+        service: zod_1.z.string().optional(),
+        entity: zod_1.z.string().optional(),
+        format: zod_1.z.enum(["concise", "detailed"]).default("concise").optional(),
+    })
+        .strict();
+    const inputSchema = {
+        service: inputZod.shape.service,
+        entity: inputZod.shape.entity,
+        format: inputZod.shape.format,
+    };
+    server.registerTool("cap_describe_model", {
+        title: "cap_describe_model",
+        description: "Describe CAP services/entities and their fields, keys, and example tool calls. Use this to guide LLMs how to call entity wrapper tools.",
+        inputSchema,
+    }, async (rawArgs) => {
+        const args = inputZod.parse(rawArgs);
+        const CDS = global.cds;
+        const refl = CDS.reflect(CDS.model);
+        const listServices = () => {
+            const names = Object.values(CDS.services || {})
+                .map((s) => s?.definition?.name || s?.name)
+                .filter(Boolean);
+            return { services: [...new Set(names)].sort() };
+        };
+        const listEntities = (service) => {
+            const all = Object.values(refl.entities || {}) || [];
+            const filtered = service
+                ? all.filter((e) => String(e.name).startsWith(service + "."))
+                : all;
+            return {
+                entities: filtered.map((e) => e.name).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];
+            if (!ent)
+                return {
+                    error: `Entity not found: ${entity}${service ? ` (service ${service})` : ""}`,
+                };
+            const elements = Object.entries(ent.elements || {}).map(([name, el]) => ({
+                name,
+                type: el.type,
+                key: !!el.key,
+                target: el.target || undefined,
+                isArray: !!el.items,
+            }));
+            const keys = elements.filter((e) => e.key).map((e) => e.name);
+            const sampleTop = 5;
+            const shortFields = elements.slice(0, 5).map((e) => e.name);
+            // Match wrapper tool naming: Service_Entity_mode
+            const entName = String(ent?.name || "entity");
+            const svcPart = service || entName.split(".")[0] || "Service";
+            const entityBase = entName.split(".").pop() || "Entity";
+            const listName = `${svcPart}_${entityBase}_query`;
+            const getName = `${svcPart}_${entityBase}_get`;
+            return {
+                service,
+                entity: ent.name,
+                keys,
+                fields: elements,
+                usage: {
+                    rationale: "Entity wrapper tools expose CRUD-like operations for LLMs. Prefer query/get globally; create/update must be explicitly enabled by the developer.",
+                    guidance: "Use the *_query tool for retrieval with filters and projections; use *_get with keys for a single record; use *_create/*_update only if enabled and necessary.",
+                },
+                examples: {
+                    list_tool: listName,
+                    list_tool_payload: {
+                        top: sampleTop,
+                        select: shortFields,
+                    },
+                    get_tool: getName,
+                    get_tool_payload: keys.length ? { [keys[0]]: "<value>" } : {},
+                },
+            };
+        };
+        let json;
+        if (!args.service && !args.entity) {
+            json = { ...listServices(), ...listEntities(undefined) };
+        }
+        else if (args.service && !args.entity) {
+            json = { service: args.service, ...listEntities(args.service) };
+        }
+        else {
+            json = describeEntity(args.service, args.entity);
+        }
+        return (0, utils_1.asMcpResult)(json);
+    });
+}