@gavdi/cap-mcp 0.9.7 → 0.9.9-alpha.3

package/README.md

@@ -3,7 +3,7 @@
 > This implementation is based on the Model Context Protocol (MCP) put forward by Anthropic.
 > For more information on MCP, please have a look at their [official documentation.](https://modelcontextprotocol.io/introduction)
 
-> 🔧 **In active development - 1.0 release scheduled for Summer 2025**
+> 🔧 **In active development - 1.0 release scheduled for September 2025**
 
 # CAP-MCP Plugin
 
@@ -15,7 +15,7 @@ Transform your CAP OData services into AI-accessible resources, tools, and promp
 The Model Context Protocol bridges the gap between your enterprise data and AI agents.
 By integrating MCP with your CAP applications, you unlock:
 
-- **AI-Native Data Access**: Your CAP services become directly accessible to AI agents like Claude, enabling natural language queries against your business data
+- **AI-Native Data Access**: Your CAP services become directly accessible to MCP enabled AI agents like Claude, enabling natural language queries against your business data
 - **Enterprise Integration**: Seamlessly connect AI tools to your SAP systems, databases, and business logic
 - **Intelligent Automation**: Enable AI agents to perform complex business operations by combining multiple CAP service calls
 - **Developer Productivity**: Allow AI assistants to help developers understand, query, and work with your CAP data models
@@ -23,19 +23,11 @@ By integrating MCP with your CAP applications, you unlock:
 
 ## ⚠️ Development Status
 
-**This plugin is currently in active development (v0.9.2) and approaching production readiness.**
+**This plugin is currently in active development and approaching production readiness.**
 APIs and annotations may change in future releases. Authentication and security features are implemented and tested.
 
 Version 1.0 of the plugin is scheduled for release in Summer 2025 after final stability testing and documentation completion.
 
-## 📦 Installation
-
-```bash
-npm install @gavdi/cap-mcp
-```
-
-The plugin follows CAP's standard plugin architecture and will automatically integrate with your CAP application.
-
 ## 🚀 Quick Setup
 
 ### Prerequisites
@@ -51,6 +43,8 @@ The plugin follows CAP's standard plugin architecture and will automatically int
 npm install @gavdi/cap-mcp
 ```
 
+The plugin follows CAP's standard plugin architecture and will automatically integrate with your CAP application upon installation.
+
 ### Step 2: Configure Your CAP Application
 
 Add MCP configuration to your `package.json`:
@@ -62,7 +56,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"
     }
   }
 }
@@ -82,7 +77,7 @@ 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,
@@ -134,17 +129,6 @@ This plugin transforms your annotated CAP services into a fully functional MCP s
 - 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.
@@ -196,6 +180,33 @@ service CatalogService {
 - **Dynamic Filtering**: Complex filter expressions using OData syntax
 - **Flexible Selection**: Choose specific fields and sort orders
 
+### 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.
+
+Example:
+
+```cds
+  // Wrap Books entity as tools for query/get/create/update (demo)
+  annotate CatalogService.Books with @mcp.wrap: {
+    tools: true,
+    modes: [
+      'query',
+      'get',
+      'create',
+      'update'
+    ],
+    hint : 'Use for read and write demo operations'
+  };
+```
+
 ### Tool Annotations
 
 Convert CAP functions and actions into executable AI tools:
@@ -251,6 +262,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,
@@ -275,6 +287,7 @@ Configure the MCP plugin through your CAP application's `package.json` or `.cdsr
 | `name` | string | package.json name | MCP server name |
 | `version` | string | package.json version | MCP server version |
 | `auth` | `"inherit"` \| `"none"` | `"inherit"` | Authentication mode |
+| `instructions` | string | `null` | MCP server instructions for agents |
 | `capabilities.resources.listChanged` | boolean | `true` | Enable resource list change notifications |
 | `capabilities.resources.subscribe` | boolean | `false` | Enable resource subscriptions |
 | `capabilities.tools.listChanged` | boolean | `true` | Enable tool list change notifications |
@@ -537,9 +550,24 @@ npm test -- --testPathPattern=integration
 ## 🚨 Performance & Limitations
 
 ### Known Limitations
-- **SDK Bug**: Dynamic resource queries require all query parameters due to `@modelcontextprotocol/sdk` RFC template string issue
-- **Authentication Inheritance**: MCP authentication is tightly coupled to CAP's authentication system
-- **Session Cleanup**: MCP sessions are cleaned up on HTTP connection close, not on explicit disconnect
+
+#### No Interactive Authentication Support
+**The plugin currently does NOT support interactive OAuth flows** that allow end-users to log in through MCP clients like Claude Desktop, Cursor, or other consumer MCP applications.
+
+**What this means:**
+- ✅ Works with custom MCP clients that can inject pre-obtained bearer tokens
+- ✅ Works in development with `dummy` authentication  
+- ❌ **Does NOT work with Claude Desktop, Cursor, or similar clients expecting OAuth login flows**
+- ❌ End-users cannot authenticate interactively when connecting
+
+**Technical Context:** This limitation exists due to architectural constraints in the current Model Context Protocol SDK. The MCP community is actively working on a solution that would enable proper interactive authentication flows, but no timeline has been announced. This is expected to be resolved in the second half of 2025.
+
+**Workarounds:**
+- **For Development**: Use `"auth": { "kind": "dummy" }` in your CAP configuration
+- **For Production**: Custom MCP clients must obtain valid bearer tokens through your CAP application's existing authentication flow and include them in requests as `Authorization: Bearer <token>`
+
+#### SDK Bug
+- **Dynamic Resource Queries**: Require all query parameters due to `@modelcontextprotocol/sdk` RFC template string issue
 
 ### Performance Considerations
 - **Large Datasets**: Use `resource: ['top']` or similar constraints for entities with many records

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/annotations.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpPromptAnnotation = exports.McpToolAnnotation = exports.McpResourceAnnotation = exports.McpAnnotation = exports.McpAnnotations = exports.McpAnnotationKey = void 0;
+exports.parseAnnotations = parseAnnotations;
+const utils_1 = require("./utils");
+const DEFAULT_ALL_RESOURCE_OPTIONS = new Set([
+    "filter",
+    "sort",
+    "top",
+    "skip",
+    "select",
+]);
+exports.McpAnnotationKey = "@mcp";
+exports.McpAnnotations = {
+    // Resource annotations for MCP
+    MCP_RESOURCE: "@mcp.resource",
+    // Tool annotations for MCP
+    MCP_TOOL_NAME: "@mcp.tool.name",
+    MCP_TOOL_DESCRIPTION: "@mcp.tool.description",
+    // Prompt annotations for MCP
+    MCP_PROMPT: "@mcp.prompt",
+};
+class McpAnnotation {
+    _target;
+    _serviceName;
+    constructor(target, serviceName) {
+        this._target = target;
+        this._serviceName = serviceName;
+    }
+    get target() {
+        return this._target;
+    }
+    get serviceName() {
+        return this._serviceName;
+    }
+}
+exports.McpAnnotation = McpAnnotation;
+class McpResourceAnnotation extends McpAnnotation {
+    _includeAll;
+    _functionalities;
+    _properties;
+    constructor(target, serviceName, includeAll, functionalities, properties) {
+        super(target, serviceName);
+        this._includeAll = includeAll;
+        this._functionalities = functionalities;
+        this._properties = properties;
+    }
+    get includeAll() {
+        return this._includeAll;
+    }
+    get functionalities() {
+        return this._functionalities;
+    }
+    get properties() {
+        return this._properties;
+    }
+}
+exports.McpResourceAnnotation = McpResourceAnnotation;
+class McpToolAnnotation extends McpAnnotation {
+    _name;
+    _description;
+    _parameters;
+    _entityKey;
+    _operationKind;
+    _keyTypeMap;
+    constructor(name, description, operation, serviceName, parameters, entityKey, operationKind, keyTypeMap) {
+        super(operation, serviceName);
+        this._name = name;
+        this._description = description;
+        this._parameters = parameters;
+        this._entityKey = entityKey;
+        this._operationKind = operationKind;
+        this._keyTypeMap = keyTypeMap;
+    }
+    get name() {
+        return this._name;
+    }
+    get description() {
+        return this._description;
+    }
+    get parameters() {
+        return this._parameters;
+    }
+    get entityKey() {
+        return this._entityKey;
+    }
+    get operationKind() {
+        return this._operationKind;
+    }
+    get keyTypeMap() {
+        return this._keyTypeMap;
+    }
+}
+exports.McpToolAnnotation = McpToolAnnotation;
+class McpPromptAnnotation extends McpAnnotation {
+    _name;
+    _template;
+    constructor(target, serviceName, name, template) {
+        super(target, serviceName);
+        this._name = name;
+        this._template = template;
+    }
+    get name() {
+        return this._name;
+    }
+    get template() {
+        return this._template;
+    }
+}
+exports.McpPromptAnnotation = McpPromptAnnotation;
+function parseAnnotations(services) {
+    const annotations = [];
+    for (const serviceName of Object.keys(services)) {
+        const srv = services[serviceName];
+        if (srv.name === "CatalogService") {
+            utils_1.LOGGER.debug("SERVICE: ", srv.model.definitions);
+        }
+        const entities = srv.entities;
+        const operations = srv.operations; // Refers to action and function imports
+        // Find entities
+        for (const entityName of Object.keys(entities)) {
+            const target = entities[entityName];
+            const res = findEntityAnnotations(target, entityName, srv);
+            if (target.actions) {
+                const bound = parseBoundOperations(target.actions, entityName, target, srv);
+                if (bound && bound.length > 0) {
+                    annotations.push(...bound);
+                }
+            }
+            if (!res)
+                continue;
+            annotations.push(res);
+        }
+        // Find operations
+        for (const operationName of Object.keys(operations)) {
+            const op = operations[operationName];
+            const res = findOperationAnnotations(op, operationName, srv);
+            if (!res)
+                continue;
+            annotations.push(res);
+        }
+    }
+    const result = formatAnnotations(annotations);
+    return result;
+}
+function formatAnnotations(annotationList) {
+    const result = new Map();
+    for (const annotation of annotationList) {
+        if (annotation.operation) {
+            if (!annotation.annotations[exports.McpAnnotations.MCP_TOOL_NAME] ||
+                !annotation.annotations[exports.McpAnnotations.MCP_TOOL_DESCRIPTION]) {
+                utils_1.LOGGER.error(`Invalid annotation found for operation`, annotation);
+                throw new Error(`Invalid annotations for operation '${annotation.operation}'`);
+            }
+            else if (typeof annotation.annotations[exports.McpAnnotations.MCP_TOOL_NAME] !==
+                "string" ||
+                typeof annotation.annotations[exports.McpAnnotations.MCP_TOOL_DESCRIPTION] !==
+                    "string") {
+                utils_1.LOGGER.error("Invalid data for annotations", annotation);
+                throw new Error(`Invalid annotation data for operation '${annotation.operation}'`);
+            }
+            const entry = new McpToolAnnotation(annotation.annotations[exports.McpAnnotations.MCP_TOOL_NAME], annotation.annotations[exports.McpAnnotations.MCP_TOOL_DESCRIPTION], annotation.operation, annotation.serviceName, mapOperationInput(annotation.context), // TODO: Parse the parameters from the context and place them in the class
+            annotation.entityKey, annotation.operationKind, annotation.keyTypeMap);
+            result.set(entry.target, entry);
+            continue;
+        }
+        if (!annotation.entityKey) {
+            utils_1.LOGGER.error("Invalid entry", annotation);
+            throw new Error(`Invalid annotated entry found with no target`);
+        }
+        if (!annotation.annotations[exports.McpAnnotations.MCP_RESOURCE]) {
+            utils_1.LOGGER.error("No valid annotations found for entry", annotation);
+            throw new Error(`Invalid annotations for entry target: '${annotation.entityKey}'`);
+        }
+        const includeAll = annotation.annotations[exports.McpAnnotations.MCP_RESOURCE] === true;
+        const functionalities = Array.isArray(annotation.annotations[exports.McpAnnotations.MCP_RESOURCE])
+            ? new Set(annotation.annotations[exports.McpAnnotations.MCP_RESOURCE])
+            : DEFAULT_ALL_RESOURCE_OPTIONS;
+        const entry = new McpResourceAnnotation(annotation.entityKey, annotation.serviceName, includeAll, functionalities, (0, utils_1.parseEntityElements)(annotation.context));
+        result.set(entry.target, entry);
+    }
+    utils_1.LOGGER.debug("Formatted annotations", result);
+    return result;
+}
+function findEntityAnnotations(entry, entityKey, service) {
+    const annotations = findAnnotations(entry);
+    return Object.keys(annotations).length > 0
+        ? {
+            serviceName: service.name,
+            annotations: annotations,
+            entityKey: entityKey,
+            context: entry,
+        }
+        : undefined;
+}
+function findOperationAnnotations(operation, operationName, service) {
+    const annotations = findAnnotations(operation);
+    return Object.keys(annotations).length > 0
+        ? {
+            serviceName: service.name,
+            annotations: annotations,
+            operation: operationName,
+            operationKind: operation.kind,
+            context: operation,
+        }
+        : undefined;
+}
+function parseBoundOperations(operations, entityKey, entity, service) {
+    const res = new Array();
+    for (const [operationName, operation] of Object.entries(operations)) {
+        const annotation = findBoundOperationAnnotations(operation, operationName, entityKey, service);
+        if (!annotation)
+            continue;
+        annotation.keyTypeMap = new Map();
+        for (const [k, v] of Object.entries(entity.keys)) {
+            if (!v.type) {
+                utils_1.LOGGER.error("Invalid key type", k);
+                throw new Error("Invalid key type found for bound operation");
+            }
+            annotation.keyTypeMap.set(k, v.type.replace("cds.", ""));
+        }
+        res.push(annotation);
+    }
+    return res;
+}
+function findBoundOperationAnnotations(operation, operationName, entityKey, service) {
+    const annotations = findAnnotations(operation);
+    return Object.keys(annotations).length > 0
+        ? {
+            serviceName: service.name,
+            annotations: annotations,
+            operation: operationName,
+            operationKind: operation.kind,
+            entityKey: entityKey,
+            context: operation,
+        }
+        : undefined;
+}
+function findAnnotations(entry) {
+    const annotations = {};
+    for (const [k, v] of Object.entries(entry)) {
+        if (!k.includes(exports.McpAnnotationKey))
+            continue;
+        annotations[k] = v;
+    }
+    return annotations;
+}
+function mapOperationInput(ctx) {
+    const params = ctx["params"];
+    if (!params)
+        return undefined;
+    const result = new Map();
+    for (const [k, v] of Object.entries(params)) {
+        result.set(k, v.type.replace("cds.", ""));
+    }
+    return result.size > 0 ? result : undefined;
+}

package/lib/auth/adapter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/auth/handler.js

@@ -2,8 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.authHandlerFactory = authHandlerFactory;
 exports.errorHandlerFactory = errorHandlerFactory;
+const logger_1 = require("../logger");
 /** JSON-RPC 2.0 error code for unauthorized requests */
 const RPC_UNAUTHORIZED = 10;
+/** HTTP Authenticate header **/
+const WWW_AUTHENTICATE = "WWW-Authenticate";
 /* @ts-ignore */
 const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
 /**
@@ -31,9 +34,15 @@ const cds = global.cds || require("@sap/cds"); // This is a work around for miss
  * @throws {500} When CAP context is not properly loaded
  */
 function authHandlerFactory() {
-    const authKind = cds.env.requires.auth.kind;
     return (req, res, next) => {
+        const auth = cds.env.requires.auth;
+        const authKind = auth.kind;
+        const credentials = auth.credentials;
         if (!req.headers.authorization && authKind !== "dummy") {
+            logger_1.LOGGER.warn("No valid authorization header provided");
+            // We need to return a WWW-Authenticate response header here with .well-known metadata
+            // Otherwise the MCP client will not be able to figure out the auth flow
+            res.setHeader(WWW_AUTHENTICATE, `Bearer error='"invalid_token", resource_metadata="${credentials?.url}/.well-known/oauth-protected-resource"`);
             res.status(401).json({
                 jsonrpc: "2.0",
                 error: {
@@ -58,6 +67,9 @@ function authHandlerFactory() {
         }
         const user = ctx.user;
         if (!user || user === cds.User.anonymous) {
+            // We need to return a WWW-Authenticate response header here with .well-known metadata
+            // Otherwise the MCP client will not be able to figure out the auth flow
+            res.setHeader(WWW_AUTHENTICATE, `Bearer error='"invalid_token", resource_metadata="${credentials?.url}/.well-known/oauth-protected-resource"`);
             res.status(401).json({
                 jsonrpc: "2.0",
                 error: {

package/lib/auth/mock.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });