@gavdi/cap-mcp 1.4.1 → 1.5.0

package/README.md

@@ -1,7 +1,6 @@
 # CAP MCP Plugin - AI With Ease
-![NPM Version](https://img.shields.io/npm/v/%40gavdi%2Fcap-mcp) ![NPM License](https://img.shields.io/npm/l/%40gavdi%2Fcap-mcp) ![NPM Downloads](https://img.shields.io/npm/dm/%40gavdi%2Fcap-mcp) ![GitHub commits since latest release](https://img.shields.io/github/commits-since/gavdilabs/cap-mcp-plugin/latest)
-
 
+![NPM Version](https://img.shields.io/npm/v/%40gavdi%2Fcap-mcp) ![NPM License](https://img.shields.io/npm/l/%40gavdi%2Fcap-mcp) ![NPM Downloads](https://img.shields.io/npm/dm/%40gavdi%2Fcap-mcp) ![GitHub commits since latest release](https://img.shields.io/github/commits-since/gavdilabs/cap-mcp-plugin/latest)
 
 > 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)
@@ -99,6 +98,7 @@ cds serve
 ```
 
 The MCP server will be available at:
+
 - **MCP Endpoint**: `http://localhost:4004/mcp`
 - **Health Check**: `http://localhost:4004/mcp/health`
 
@@ -176,6 +176,7 @@ service CatalogService {
 ```
 
 **Generated MCP Resource Capabilities:**
+
 - **OData v4 Query Support**: `$filter`, `$orderby`, `$top`, `$skip`, `$select`, `$expand`
 - **Natural Language Queries**: "Find books by Stephen King with stock > 20"
 - **Dynamic Filtering**: Complex filter expressions using OData syntax
@@ -236,23 +237,27 @@ entity Users {
 ```
 
 **How It Works:**
+
 - Fields marked with `@mcp.omit` are automatically filtered from all MCP responses
 - Applies to:
   - **Resources**: Field will not appear in resource read operations
   - **Wrapped Entities**: Omission applies to all entity wrapper operations
 
 **Common Use Cases:**
+
 - **Security**: Hide information sensitive to functionality or business operations
 - **Privacy**: Protect personal identifiers
 - **Internal Data**: Exclude internal notes, audit logs, or system-only fields
 - **Compliance**: Ensure GDPR/CCPA compliance by hiding sensitive personal data
 
 **Important Notes:**
+
 - Omitted fields are **only excluded from outputs** - they can still be provided as inputs for create/update operations
 - The annotation works alongside the CAP standard annotation `@Core.Computed` for comprehensive field control
 - Omitted fields remain queryable in the CAP service - only MCP responses are filtered
 
 **Example with Multiple Annotations:**
+
 ```cds
 entity Products {
   key ID          : Integer;
@@ -325,11 +330,13 @@ 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
@@ -342,6 +349,7 @@ Provide contextual descriptions for individual properties and parameters using t
 #### Where to Use Hints
 
 **Resource Entity Properties**
+
 ```cds
 entity Books {
   key ID    : Integer @mcp.hint: 'Must be a unique number not already in the system';
@@ -351,6 +359,7 @@ entity Books {
 ```
 
 **Array Elements**
+
 ```cds
 entity Authors {
   key ID          : Integer;
@@ -360,6 +369,7 @@ entity Authors {
 ```
 
 **Function/Action Parameters**
+
 ```cds
 @mcp: {
   name       : 'books-by-author',
@@ -372,6 +382,7 @@ function getBooksByAuthor(
 ```
 
 **Complex Type Fields**
+
 ```cds
 type TValidQuantities {
   positiveOnly : Integer @mcp.hint: 'Only takes in positive numbers, i.e. no negative values such as -1'
@@ -381,6 +392,7 @@ type TValidQuantities {
 #### How Hints Are Used
 
 Hints are automatically incorporated into:
+
 - **Resource Descriptions**: Field-level guidance in entity wrapper tools (query/get/create/update/delete)
 - **Tool Parameter Schemas**: Enhanced parameter descriptions visible to AI agents
 - **Input Validation**: Context for AI agents when constructing function calls
@@ -388,6 +400,7 @@ Hints are automatically incorporated into:
 #### Example: Enhanced Tool Experience
 
 Without `@mcp.hint`:
+
 ```json
 {
   "tool": "CatalogService_Books_create",
@@ -399,6 +412,7 @@ Without `@mcp.hint`:
 ```
 
 With `@mcp.hint`:
+
 ```json
 {
   "tool": "CatalogService_Books_create",
@@ -418,16 +432,20 @@ With `@mcp.hint`:
 #### Best Practices
 
 1. **Be Specific**: Provide concrete examples and constraints
+
    - ❌ Bad: `@mcp.hint: 'Author name'`
    - ✅ Good: `@mcp.hint: 'Full name of the author (e.g., "Ernest Hemingway")'`
 
 2. **Include Constraints**: Document validation rules and business logic
+
    - ✅ `@mcp.hint: 'Must be between 0 and 999, representing quantity in stock'`
 
 3. **Clarify Foreign Keys**: Help AI agents understand associations
+
    - ✅ `@mcp.hint: 'Foreign key reference to Authors.ID'`
 
 4. **Explain Business Context**: Add domain-specific information
+
    - ✅ `@mcp.hint: 'ISBN-13 format, used for unique book identification'`
 
 5. **Avoid Redundancy**: Don't repeat what's obvious from the field name and type
@@ -492,22 +510,24 @@ Configure the MCP plugin through your CAP application's `package.json` or `.cdsr
 
 ### Configuration Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `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 |
-| `capabilities.prompts.listChanged` | boolean | `true` | Enable prompt list change notifications |
+| Option                               | Type                    | Default              | Description                                                                 |
+| ------------------------------------ | ----------------------- | -------------------- | --------------------------------------------------------------------------- |
+| `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                                          |
+| `enable_model_description`           | boolean                 | `true`               | Determines whether the MCP server should include the model description tool |
+| `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                                       |
+| `capabilities.prompts.listChanged`   | boolean                 | `true`               | Enable prompt list change notifications                                     |
 
 ### Authentication Configuration
 
 The plugin supports two authentication modes:
 
 #### `"inherit"` Mode (Default)
+
 Uses your CAP application's existing authentication system:
 
 ```json
@@ -526,6 +546,7 @@ Uses your CAP application's existing authentication system:
 ```
 
 #### `"none"` Mode (Development/Testing)
+
 Disables authentication completely:
 
 ```json
@@ -541,6 +562,7 @@ Disables authentication completely:
 **⚠️ Security Warning**: Only use `"none"` mode in development environments. Never deploy to production without proper authentication.
 
 #### Authentication Flow
+
 1. MCP client connects to `/mcp` endpoint
 2. If the authentication style used is OAuth, the OAuth flow will be executed
 3. CAP authentication middleware validates credentials (if `auth: "inherit"`)
@@ -550,6 +572,7 @@ Disables authentication completely:
 ### Automatic Features
 
 The plugin automatically:
+
 - Scans your CAP service definitions for `@mcp` annotations
 - Generates appropriate MCP resources, tools, and prompts
 - Creates ResourceTemplates with proper OData v4 query parameter support
@@ -570,6 +593,7 @@ While this shows how this example CDS annotation works, the possibilities are en
 ## 📋 Business Case Example: Workflow Approval Management
 
 ### The Setup
+
 Your CAP service includes a workflow management system with MCP integration:
 
 ```cds
@@ -587,16 +611,19 @@ service WorkflowService {
 ### The Interaction Flow
 
 **1. User Query**
+
 ```
 User: "Hey <Agent>, do I have any workflows pending approval?"
 ```
 
 **2. AI Agent Processing**
+
 - Agent recognizes this as a request for pending approval information
 - Identifies the `get-my-pending-approval` tool as the appropriate method
 - Determines the user's ID from context (session, authentication, etc.)
 
 **3. MCP Tool Execution**
+
 ```javascript
 // Agent calls the MCP tool
 {
@@ -608,12 +635,14 @@ User: "Hey <Agent>, do I have any workflows pending approval?"
 ```
 
 **4. CAP Service Processing**
+
 - Your CAP service receives the tool call
 - Executes `getPendingApproval("john.doe@company.com")`
 - Queries your workflow database/system
 - Returns structured workflow data
 
 **5. AI Response**
+
 ```
 Agent: "You have 3 workflows pending your approval:
 
@@ -636,6 +665,7 @@ Would you like me to help you review any of these in detail?"
 ```
 
 ### Business Value
+
 - **Instant Access**: No need to log into workflow systems or navigate complex UIs
 - **Contextual Intelligence**: AI can prioritize based on urgency, amounts, or business rules
 - **Natural Interaction**: Users can ask follow-up questions in plain language
@@ -702,11 +732,13 @@ This project is licensed under the Apache-2.0 License - see the [LICENSE.md](LIC
 ### Common Issues
 
 #### MCP Server Not Starting
+
 - **Check Port Availability**: Ensure port 4004 is not in use by another process
 - **Verify CAP Service**: Make sure your CAP application starts successfully with `cds serve`
 - **Authentication Issues**: If using `auth: "inherit"`, ensure your CAP authentication is properly configured
 
 #### MCP Client Connection Failures
+
 ```bash
 # Check if MCP endpoint is accessible
 curl http://localhost:4004/mcp/health
@@ -716,21 +748,25 @@ curl http://localhost:4004/mcp/health
 ```
 
 #### Annotation Not Working
+
 - **Syntax Check**: Verify your `@mcp` annotation syntax matches the examples
 - **Service Deployment**: Ensure annotated entities/functions are properly deployed
 - **Case Sensitivity**: Check that annotation properties use correct casing (`resource`, `tool`, `prompts`)
 
 #### OData Query Issues
+
 - **SDK Bug Workaround**: Due to the known `@modelcontextprotocol/sdk` bug, provide all query parameters when using dynamic queries
 - **Parameter Validation**: Ensure query parameters match OData v4 syntax
 
 #### Performance Issues
+
 - **Resource Filtering**: Use specific `resource` arrays instead of `true` for large datasets
 - **Query Optimization**: Implement proper database indexes for frequently queried fields
 
 ### Debugging
 
 #### Enable Debug Logging
+
 ```json
 {
   "cds": {
@@ -744,6 +780,7 @@ curl http://localhost:4004/mcp/health
 ```
 
 #### Test MCP Implementation
+
 ```bash
 # Use MCP Inspector for interactive testing
 npm run inspect
@@ -761,14 +798,17 @@ 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
 
 ### Performance Considerations
+
 - **Large Datasets**: Use `resource: ['top']` or similar constraints for entities with many records
 - **Complex Queries**: OData query parsing adds overhead - consider caching for frequently accessed data
 - **Concurrent Sessions**: Each MCP client creates a separate session - monitor memory usage with many clients
 
 ### Scale Recommendations
+
 - **Development**: No specific limits
 - **Production**: Test with expected concurrent MCP client count
 - **Enterprise**: Consider load balancing for high-availability scenarios
@@ -781,6 +821,7 @@ npm test -- --testPathPattern=integration
 - [MCP Inspector Tool](https://github.com/modelcontextprotocol/inspector)
 
 ---
+
 (c) Copyright by Gavdi Labs 2025 - All Rights Reserved
 
 **Transform your CAP applications into AI-ready systems with the power of the Model Context Protocol.**

package/lib/annotations/constants.js

@@ -22,6 +22,7 @@ exports.MCP_ANNOTATION_MAPPING = new Map([
     ["@mcp.wrap", "wrap"],
     ["@mcp.wrap.tools", "wrap.tools"],
     ["@mcp.wrap.modes", "wrap.modes"],
+    ["@mcp.wrap.name", "wrap.name"],
     ["@mcp.wrap.hint", "wrap.hint"],
     ["@mcp.wrap.hint.get", "wrap.hint.get"],
     ["@mcp.wrap.hint.query", "wrap.hint.query"],

package/lib/auth/factory.js

@@ -5,10 +5,32 @@ exports.errorHandlerFactory = errorHandlerFactory;
 const xsuaa_service_1 = require("./xsuaa-service");
 const utils_1 = require("./utils");
 const logger_1 = require("../logger");
+const host_resolver_1 = require("./host-resolver");
 /** JSON-RPC 2.0 error code for unauthorized requests */
 const RPC_UNAUTHORIZED = 10;
 /* @ts-ignore */
 const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
+/**
+ * Sends a 401 response with RFC 9728 compliant WWW-Authenticate header.
+ * The header includes `resource_metadata` pointing to the protected resource metadata endpoint.
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param message - Error message for the JSON-RPC response
+ */
+function send401WithMetadata(req, res, message) {
+    const baseUrl = (0, host_resolver_1.buildPublicBaseUrl)(req);
+    const metadataUrl = `${baseUrl}/.well-known/oauth-protected-resource`;
+    res.set("WWW-Authenticate", `Bearer resource_metadata="${metadataUrl}"`);
+    res.status(401).json({
+        jsonrpc: "2.0",
+        error: {
+            code: RPC_UNAUTHORIZED,
+            message,
+            id: null,
+        },
+    });
+}
 /**
  * Creates an Express middleware for MCP authentication validation.
  *
@@ -39,14 +61,7 @@ function authHandlerFactory() {
     logger_1.LOGGER.debug("Authentication kind", authKind);
     return async (req, res, next) => {
         if (!req.headers.authorization && authKind !== "dummy") {
-            res.status(401).json({
-                jsonrpc: "2.0",
-                error: {
-                    code: RPC_UNAUTHORIZED,
-                    message: "Unauthorized",
-                    id: null,
-                },
-            });
+            send401WithMetadata(req, res, "Unauthorized");
             return;
         }
         // For XSUAA/JWT auth types, use @sap/xssec for validation
@@ -54,14 +69,7 @@ function authHandlerFactory() {
             xsuaaService?.isConfigured()) {
             const securityContext = await xsuaaService.createSecurityContext(req);
             if (!securityContext) {
-                res.status(401).json({
-                    jsonrpc: "2.0",
-                    error: {
-                        code: RPC_UNAUTHORIZED,
-                        message: "Invalid or expired token",
-                        id: null,
-                    },
-                });
+                send401WithMetadata(req, res, "Invalid or expired token");
                 return;
             }
             // Add security context to request for later use
@@ -82,14 +90,7 @@ function authHandlerFactory() {
         }
         const user = ctx.user;
         if (!user || user === cds.User.anonymous) {
-            res.status(401).json({
-                jsonrpc: "2.0",
-                error: {
-                    code: RPC_UNAUTHORIZED,
-                    message: "Unauthorized",
-                    id: null,
-                },
-            });
+            send401WithMetadata(req, res, "Unauthorized");
             return;
         }
         return next();
@@ -116,13 +117,17 @@ function authHandlerFactory() {
  * @param next - Express next function for passing unhandled errors
  */
 function errorHandlerFactory() {
-    return (err, _, res, next) => {
-        if (err === 401 || err === 403) {
-            res.status(err).json({
+    return (err, req, res, next) => {
+        if (err === 401) {
+            send401WithMetadata(req, res, "Unauthorized");
+            return;
+        }
+        if (err === 403) {
+            res.status(403).json({
                 jsonrpc: "2.0",
                 error: {
                     code: RPC_UNAUTHORIZED,
-                    message: err === 401 ? "Unauthorized" : "Forbidden",
+                    message: "Forbidden",
                     id: null,
                 },
             });

package/lib/auth/host-resolver.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Host resolution for multi-tenant and reverse proxy scenarios.
+ *
+ * This module provides utilities to determine the correct public-facing host
+ * when the application runs behind SAP Approuter or other reverse proxies.
+ *
+ * Header Priority (based on SAP Approuter documentation):
+ * 1. x-forwarded-host - Standard header set by Approuter (setXForwardedHeaders=true, default)
+ * 2. x-custom-host    - Only when EXTERNAL_REVERSE_PROXY=true
+ * 3. APP_DOMAIN env   - Fallback for HTTP/2 bug where X-Forwarded headers may be missing
+ * 4. host header      - Local development fallback
+ *
+ * @module host-resolver
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHostResolverEnv = getHostResolverEnv;
+exports.isProductionEnv = isProductionEnv;
+exports.extractSubdomain = extractSubdomain;
+exports.normalizeHost = normalizeHost;
+exports.resolveEffectiveHost = resolveEffectiveHost;
+exports.getProtocol = getProtocol;
+exports.buildPublicBaseUrl = buildPublicBaseUrl;
+const logger_1 = require("../logger");
+/**
+ * Reads environment configuration for host resolution.
+ * Separated for testability.
+ */
+function getHostResolverEnv() {
+    return {
+        appDomain: process.env.APP_DOMAIN,
+        externalReverseProxy: process.env.EXTERNAL_REVERSE_PROXY === "true",
+        nodeEnv: process.env.NODE_ENV,
+    };
+}
+/**
+ * Determines if the environment is production.
+ * Production = NODE_ENV explicitly set to "production".
+ */
+function isProductionEnv(env) {
+    return env.nodeEnv === "production";
+}
+/**
+ * Extracts subdomain from a hostname.
+ * For "tenant1.myapp.cloud", returns "tenant1".
+ * For "myapp.cloud" or "localhost", returns "".
+ */
+function extractSubdomain(host, appDomain) {
+    if (!host || !appDomain)
+        return "";
+    // Normalize: remove port, lowercase
+    const cleanHost = host.split(":")[0].toLowerCase();
+    const cleanDomain = appDomain.toLowerCase();
+    if (cleanHost.endsWith(`.${cleanDomain}`)) {
+        return cleanHost.slice(0, -(cleanDomain.length + 1));
+    }
+    return "";
+}
+/**
+ * Safely gets the host header from request.
+ * Handles cases where req.get might not be available (e.g., in tests).
+ */
+function getHostHeader(req) {
+    if (typeof req.get === "function") {
+        return req.get("host") || "";
+    }
+    return req.headers?.host || "";
+}
+/**
+ * Normalizes a host header value.
+ * - Takes first value if comma-separated (proxy chain)
+ * - Trims whitespace
+ */
+function normalizeHost(headerValue) {
+    if (!headerValue)
+        return "";
+    // Take first host if comma-separated (multiple proxies)
+    return headerValue.split(",")[0].trim();
+}
+/**
+ * Resolves the effective public-facing host for the current request.
+ *
+ * @param req - Express request object
+ * @param env - Environment configuration (optional, uses process.env by default)
+ * @returns The resolved public host (without protocol)
+ */
+function resolveEffectiveHost(req, env = getHostResolverEnv()) {
+    const isProduction = isProductionEnv(env);
+    // Priority 1: x-forwarded-host (SAP Approuter standard)
+    const xfh = normalizeHost(req.headers["x-forwarded-host"]);
+    if (xfh) {
+        logger_1.LOGGER.debug("[host-resolver] using x-forwarded-host", { host: xfh });
+        return xfh;
+    }
+    // Priority 2: x-custom-host (only with EXTERNAL_REVERSE_PROXY)
+    if (env.externalReverseProxy) {
+        const xch = normalizeHost(req.headers["x-custom-host"]);
+        if (xch) {
+            logger_1.LOGGER.debug("[host-resolver] using x-custom-host", { host: xch });
+            return xch;
+        }
+    }
+    // Priority 3: APP_DOMAIN fallback (production only)
+    if (env.appDomain && isProduction) {
+        logger_1.LOGGER.info("[host-resolver] using APP_DOMAIN fallback", {
+            host: env.appDomain,
+        });
+        return env.appDomain;
+    }
+    // Priority 4: Raw host header
+    const host = normalizeHost(getHostHeader(req)) || "localhost";
+    if (isProduction) {
+        logger_1.LOGGER.warn("[host-resolver] using raw host in production", { host });
+    }
+    return host;
+}
+/**
+ * Determines the protocol (http/https) for URL construction.
+ *
+ * @param req - Express request object
+ * @param env - Environment configuration (optional)
+ * @returns Protocol string ('http' or 'https')
+ */
+function getProtocol(req, env = getHostResolverEnv()) {
+    // Check x-forwarded-proto first (most reliable behind proxy)
+    const forwardedProto = req.headers["x-forwarded-proto"];
+    if (forwardedProto) {
+        // Take first value if comma-separated
+        return forwardedProto.split(",")[0].trim();
+    }
+    // Default to HTTPS in production
+    return isProductionEnv(env) ? "https" : req.protocol;
+}
+/**
+ * Builds the complete public base URL for the current request.
+ * Combines protocol and resolved host.
+ *
+ * @param req - Express request object
+ * @param env - Environment configuration (optional)
+ * @returns Full base URL (e.g., "https://tenant1.myapp.cloud")
+ */
+function buildPublicBaseUrl(req, env = getHostResolverEnv()) {
+    const protocol = getProtocol(req, env);
+    const host = resolveEffectiveHost(req, env);
+    return `${protocol}://${host}`;
+}

package/lib/auth/utils.js

@@ -15,6 +15,7 @@ const factory_1 = require("./factory");
 const xsuaa_service_1 = require("./xsuaa-service");
 const handlers_1 = require("./handlers");
 const logger_1 = require("../logger");
+const host_resolver_1 = require("./host-resolver");
 /**
  * @fileoverview Authentication utilities for MCP-CAP integration.
  *
@@ -194,22 +195,6 @@ function configureOAuthProxy(expressApp) {
     }
     registerOAuthEndpoints(expressApp, credentials, kind);
 }
-/**
- * Determines the correct protocol (HTTP/HTTPS) for URL construction.
- * Accounts for reverse proxy headers and production environment defaults.
- *
- * @param req - Express request object
- * @returns Protocol string ('http' or 'https')
- */
-function getProtocol(req) {
-    // Check for reverse proxy header first (most reliable)
-    if (req.headers["x-forwarded-proto"]) {
-        return req.headers["x-forwarded-proto"];
-    }
-    // Default to HTTPS in production environments
-    const isProduction = process.env.NODE_ENV === "production" || process.env.VCAP_APPLICATION;
-    return isProduction ? "https" : req.protocol;
-}
 /**
  * Registers OAuth endpoints for XSUAA integration
  * Only called for jwt/xsuaa/ias auth types with valid credentials
@@ -237,8 +222,8 @@ function registerOAuthEndpoints(expressApp, credentials, kind) {
         const { state, redirect_uri, client_id, code_challenge, code_challenge_method, scope, } = req.query;
         // Client validation and redirect URI validation is handled by XSUAA
         // We delegate all client management to XSUAA's built-in OAuth server
-        const protocol = getProtocol(req);
-        const redirectUri = redirect_uri || `${protocol}://${req.get("host")}/oauth/callback`;
+        const baseUrl = (0, host_resolver_1.buildPublicBaseUrl)(req);
+        const redirectUri = redirect_uri || `${baseUrl}/oauth/callback`;
         const authUrl = xsuaaService.getAuthorizationUrl(redirectUri, client_id ?? "", state, code_challenge, code_challenge_method, scope);
         res.redirect(authUrl);
     });
@@ -261,8 +246,8 @@ function registerOAuthEndpoints(expressApp, credentials, kind) {
             return;
         }
         try {
-            const protocol = getProtocol(req);
-            const url = redirect_uri || `${protocol}://${req.get("host")}/oauth/callback`;
+            const baseUrl = (0, host_resolver_1.buildPublicBaseUrl)(req);
+            const url = redirect_uri || `${baseUrl}/oauth/callback`;
             const tokenData = await xsuaaService.exchangeCodeForToken(code, url, code_verifier);
             const scopedToken = await xsuaaService.getApplicationScopes(tokenData);
             logger_1.LOGGER.debug("Scopes in token:", scopedToken.scope);
@@ -283,8 +268,7 @@ function registerOAuthEndpoints(expressApp, credentials, kind) {
     });
     // OAuth Discovery endpoint
     expressApp.get("/.well-known/oauth-authorization-server", (req, res) => {
-        const protocol = getProtocol(req);
-        const baseUrl = `${protocol}://${req.get("host")}`;
+        const baseUrl = (0, host_resolver_1.buildPublicBaseUrl)(req);
         res.json({
             issuer: credentials.url,
             authorization_endpoint: `${baseUrl}/oauth/authorize`,
@@ -298,15 +282,25 @@ function registerOAuthEndpoints(expressApp, credentials, kind) {
             registration_endpoint_auth_methods_supported: ["client_secret_basic"],
         });
     });
+    // RFC 9728: OAuth 2.0 Protected Resource Metadata endpoint
+    expressApp.get("/.well-known/oauth-protected-resource", (req, res) => {
+        const baseUrl = (0, host_resolver_1.buildPublicBaseUrl)(req);
+        res.json({
+            resource: baseUrl,
+            authorization_servers: [credentials.url],
+            bearer_methods_supported: ["header"],
+            resource_documentation: `${baseUrl}/mcp/health`,
+        });
+    });
     // OAuth Dynamic Client Registration discovery endpoint (GET)
     expressApp.get("/oauth/register", async (req, res) => {
+        const baseUrl = (0, host_resolver_1.buildPublicBaseUrl)(req);
         // IAS does not support DCR so we will respond with the pre-configured client_id
         if (kind === "ias") {
-            const protocol = getProtocol(req);
             const enhancedResponse = {
                 client_id: credentials.clientid, // Add our CAP app's client ID
                 redirect_uris: req.body.redirect_uris || [
-                    `${protocol}://${req.get("host")}/oauth/callback`,
+                    `${baseUrl}/oauth/callback`,
                 ],
             };
             logger_1.LOGGER.debug("Provided static client_id during DCR registration process");
@@ -325,11 +319,10 @@ function registerOAuthEndpoints(expressApp, credentials, kind) {
             });
             const xsuaaData = await response.json();
             // Add missing required fields that MCP client expects
-            const protocol = getProtocol(req);
             const enhancedResponse = {
                 ...xsuaaData, // Keep all XSUAA fields
                 client_id: credentials.clientid, // Add our CAP app's client ID
-                redirect_uris: [`${protocol}://${req.get("host")}/oauth/callback`], // Add our callback URL for discovery
+                redirect_uris: [`${baseUrl}/oauth/callback`], // Add our callback URL for discovery
             };
             res.status(response.status).json(enhancedResponse);
         }
@@ -343,13 +336,13 @@ function registerOAuthEndpoints(expressApp, credentials, kind) {
     });
     // OAuth Dynamic Client Registration endpoint (POST) with CSRF handling
     expressApp.post("/oauth/register", async (req, res) => {
+        const baseUrl = (0, host_resolver_1.buildPublicBaseUrl)(req);
         // IAS does not support DCR so we will respond with the pre-configured client_id
         if (kind === "ias") {
-            const protocol = getProtocol(req);
             const enhancedResponse = {
                 client_id: credentials.clientid, // Add our CAP app's client ID
                 redirect_uris: req.body.redirect_uris || [
-                    `${protocol}://${req.get("host")}/oauth/callback`,
+                    `${baseUrl}/oauth/callback`,
                 ],
             };
             logger_1.LOGGER.debug("Provided static client_id during DCR registration process");
@@ -390,14 +383,12 @@ function registerOAuthEndpoints(expressApp, credentials, kind) {
             });
             const xsuaaData = await registrationResponse.json();
             // Add missing required fields that MCP client expects
-            const protocol = getProtocol(req);
             const enhancedResponse = {
                 ...xsuaaData, // Keep all XSUAA fields
                 client_id: credentials.clientid, // Add our CAP app's client ID
-                // client_secret: credentials.clientsecret, // CAP app's client secret
                 redirect_uris: req.body.redirect_uris || [
-                    `${protocol}://${req.get("host")}/oauth/callback`,
-                ], // Use client's redirect URIs
+                    `${baseUrl}/oauth/callback`,
+                ],
             };
             logger_1.LOGGER.debug("[AUTH] Register POST response", enhancedResponse);
             res.status(registrationResponse.status).json(enhancedResponse);

package/lib/config/loader.js

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

package/lib/mcp/entity-tools.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerceKeyValue = coerceKeyValue;
 exports.registerEntityWrappers = registerEntityWrappers;
 const zod_1 = require("zod");
 const utils_1 = require("../auth/utils");
@@ -61,6 +62,90 @@ async function resolveServiceInstance(serviceName) {
 // NOTE: We use plain entity names (service projection) for queries.
 const MAX_TOP = 200;
 const TIMEOUT_MS = 10_000; // Standard timeout for tool calls (ms)
+/**
+ * CDS integer types whose values can be safely represented as a JavaScript `Number`
+ * without risk of precision loss: `Integer`, `Int16`, `Int32`, `UInt8`.
+ *
+ * All values of these types are guaranteed to fit within `Number.MAX_SAFE_INTEGER`
+ * (2^53 - 1). When a key value arrives as a digit string (e.g. `"42"`),
+ * {@link coerceKeyValue} converts it to a `Number` so that CAP can resolve
+ * the entity lookup correctly.
+ *
+ * The following numeric CDS types are intentionally excluded:
+ *
+ * - `Int64` — values may exceed `Number.MAX_SAFE_INTEGER`, causing silent
+ *   precision loss. Classified under {@link PRECISION_SENSITIVE_CDS_TYPES}.
+ * - `Decimal` — arbitrary-precision type; CAP preserves these as strings
+ *   for exact arithmetic. Classified under {@link PRECISION_SENSITIVE_CDS_TYPES}.
+ * - `Double` — maps directly to IEEE 754 double-precision (identical to JS
+ *   `number`), so there is no precision concern. Excluded here because it is
+ *   a floating-point type, not an integer.
+ *
+ * @see {@link PRECISION_SENSITIVE_CDS_TYPES}
+ * @see {@link coerceKeyValue}
+ * @see https://tc39.es/ecma262/#sec-number.max_safe_integer — ECMAScript Number.MAX_SAFE_INTEGER
+ * @see https://cap.cloud.sap/docs/cds/types — CAP CDS Built-in Types
+ */
+const SAFE_INTEGER_CDS_TYPES = new Set(["Integer", "Int16", "Int32", "UInt8"]);
+/**
+ * CDS numeric types where values must be represented as strings to preserve
+ * precision: `Int64`, `Decimal`.
+ *
+ * JavaScript `Number` (IEEE 754 double-precision) cannot faithfully represent
+ * all values of these types. When a key value arrives as a `number` from the
+ * MCP tool input, {@link coerceKeyValue} normalizes it to a `string` so that
+ * CAP can handle it without silent truncation.
+ *
+ * CAP's `cds.features.ieee754compatible` setting controls whether OData
+ * responses serialize `Edm.Int64` and `Edm.Decimal` as JSON strings.
+ * Regardless of that setting, this set ensures keys are always passed as
+ * strings to the CAP runtime.
+ *
+ * `Double` is intentionally not included. It maps directly to IEEE 754
+ * double-precision — the same representation as a JavaScript `number` — so
+ * no precision is lost during coercion. The `ieee754compatible` flag does
+ * not affect `Double`.
+ *
+ * @see {@link SAFE_INTEGER_CDS_TYPES}
+ * @see {@link coerceKeyValue}
+ * @see https://www.rfc-editor.org/rfc/rfc8259#section-6 — RFC 8259, Section 6: Numbers
+ * @see https://cap.cloud.sap/docs/releases/jun24#ieee754compatible — CAP ieee754compatible
+ */
+const PRECISION_SENSITIVE_CDS_TYPES = new Set(["Int64", "Decimal"]);
+/**
+ * Coerces a key value between string and number representations based on
+ * the CDS type metadata of the target entity element.
+ *
+ * Coercion rules, applied in order:
+ *
+ * 1. Safe integer types ({@link SAFE_INTEGER_CDS_TYPES}) — digit-only strings
+ *    (e.g. `"42"`) are converted to `Number`. `UInt8` only accepts non-negative
+ *    digit strings since it is an unsigned type.
+ * 2. Precision-sensitive types ({@link PRECISION_SENSITIVE_CDS_TYPES}) — numeric
+ *    values are converted to `String` to prevent silent precision loss beyond
+ *    `Number.MAX_SAFE_INTEGER`.
+ * 3. All other types — returned unchanged.
+ *
+ * @param raw - The raw key value received from the MCP tool input.
+ * @param cdsType - The CDS type name of the key element (e.g. `"String"`, `"Integer"`).
+ * @returns The coerced value, or the original value if no coercion rule applies.
+ *
+ * @see {@link SAFE_INTEGER_CDS_TYPES}
+ * @see {@link PRECISION_SENSITIVE_CDS_TYPES}
+ */
+function coerceKeyValue(raw, cdsType) {
+    if (typeof raw === "string" && SAFE_INTEGER_CDS_TYPES.has(cdsType)) {
+        // UInt8 is unsigned — only accept non-negative digit strings
+        const pattern = cdsType === "UInt8" ? /^\d+$/ : /^-?\d+$/;
+        if (pattern.test(raw)) {
+            return Number(raw);
+        }
+    }
+    if (typeof raw === "number" && PRECISION_SENSITIVE_CDS_TYPES.has(cdsType)) {
+        return String(raw);
+    }
+    return raw;
+}
 // Map OData operators to CDS/SQL operators for better performance and readability
 const ODATA_TO_CDS_OPERATORS = new Map([
     ["eq", "="],
@@ -123,8 +208,13 @@ function registerEntityWrappers(resAnno, server, authEnabled, defaultModes, acce
  * Builds the visible tool name for a given operation mode.
  * We prefer a descriptive naming scheme that is easy for humans and LLMs:
  *   Service_Entity_mode
+ * If customName is provided via @mcp.wrap.name, uses customName_mode instead.
  */
-function nameFor(service, entity, suffix) {
+function nameFor(service, entity, suffix, customName) {
+    // Custom name takes priority - uses format: customName_suffix
+    if (customName) {
+        return `${customName}_${suffix}`;
+    }
     // Use explicit Service_Entity_suffix naming to match docs/tests
     const entityName = entity.split(".").pop(); // keep original case
     const serviceName = service.split(".").pop(); // keep original case
@@ -135,7 +225,7 @@ function nameFor(service, entity, suffix) {
  * Supports select/where/orderby/top/skip and simple text search (q).
  */
 function registerQueryTool(resAnno, server, authEnabled) {
-    const toolName = nameFor(resAnno.serviceName, resAnno.target, "query");
+    const toolName = nameFor(resAnno.serviceName, resAnno.target, "query", resAnno.wrap?.name);
     // Structured input schema for queries with guard for empty property lists
     const allKeys = Array.from(resAnno.properties.keys());
     const scalarKeys = Array.from(resAnno.properties.entries())
@@ -275,7 +365,7 @@ function registerQueryTool(resAnno, server, authEnabled) {
  * Accepts keys either as an object or shorthand (single-key) value.
  */
 function registerGetTool(resAnno, server, authEnabled) {
-    const toolName = nameFor(resAnno.serviceName, resAnno.target, "get");
+    const toolName = nameFor(resAnno.serviceName, resAnno.target, "get", resAnno.wrap?.name);
     const inputSchema = {};
     for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
         inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}. ${resAnno.propertyHints.get(k) ?? ""}`);
@@ -313,7 +403,7 @@ function registerGetTool(resAnno, server, authEnabled) {
             }
         }
         const keys = {};
-        for (const [k] of resAnno.resourceKeys.entries()) {
+        for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
             let provided = normalizedArgs[k];
             if (provided === undefined) {
                 const alt = Object.entries(normalizedArgs || {}).find(([kk]) => String(kk).toLowerCase() === String(k).toLowerCase());
@@ -324,9 +414,7 @@ function registerGetTool(resAnno, server, authEnabled) {
                 logger_1.LOGGER.warn(`Get tool missing required key`, { key: k, toolName });
                 return (0, utils_2.toolError)("MISSING_KEY", `Missing key '${k}'`);
             }
-            const raw = provided;
-            keys[k] =
-                typeof raw === "string" && /^\d+$/.test(raw) ? Number(raw) : raw;
+            keys[k] = coerceKeyValue(provided, cdsType);
         }
         logger_1.LOGGER.debug(`Executing READ on ${resAnno.target} with keys`, keys);
         try {
@@ -348,7 +436,7 @@ function registerGetTool(resAnno, server, authEnabled) {
  * Associations are exposed via <assoc>_ID fields for simplicity.
  */
 function registerCreateTool(resAnno, server, authEnabled) {
-    const toolName = nameFor(resAnno.serviceName, resAnno.target, "create");
+    const toolName = nameFor(resAnno.serviceName, resAnno.target, "create", resAnno.wrap?.name);
     const inputSchema = {};
     for (const [propName, cdsType] of resAnno.properties.entries()) {
         const isAssociation = String(cdsType).toLowerCase().includes("association");
@@ -447,7 +535,7 @@ function registerCreateTool(resAnno, server, authEnabled) {
  * Keys are required; non-key fields are optional. Associations via <assoc>_ID.
  */
 function registerUpdateTool(resAnno, server, authEnabled) {
-    const toolName = nameFor(resAnno.serviceName, resAnno.target, "update");
+    const toolName = nameFor(resAnno.serviceName, resAnno.target, "update", resAnno.wrap?.name);
     const inputSchema = {};
     // Keys required
     for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
@@ -494,14 +582,11 @@ function registerUpdateTool(resAnno, server, authEnabled) {
         }
         // Extract keys and update fields
         const keys = {};
-        for (const [k] of resAnno.resourceKeys.entries()) {
+        for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
             if (args[k] === undefined) {
-                return {
-                    isError: true,
-                    content: [{ type: "text", text: `Missing key '${k}'` }],
-                };
+                return (0, utils_2.toolError)("MISSING_KEY", `Missing key '${k}'`);
             }
-            keys[k] = args[k];
+            keys[k] = coerceKeyValue(args[k], cdsType);
         }
         // Normalize updates: prefer *_ID for associations and coerce numeric strings
         const updates = {};
@@ -569,7 +654,7 @@ function registerUpdateTool(resAnno, server, authEnabled) {
  * Requires keys to identify the entity to delete.
  */
 function registerDeleteTool(resAnno, server, authEnabled) {
-    const toolName = nameFor(resAnno.serviceName, resAnno.target, "delete");
+    const toolName = nameFor(resAnno.serviceName, resAnno.target, "delete", resAnno.wrap?.name);
     const inputSchema = {};
     // Keys required for deletion
     for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
@@ -589,7 +674,7 @@ function registerDeleteTool(resAnno, server, authEnabled) {
         }
         // Extract keys - similar to get/update handlers
         const keys = {};
-        for (const [k] of resAnno.resourceKeys.entries()) {
+        for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
             let provided = args[k];
             if (provided === undefined) {
                 // Case-insensitive key matching (like in get handler)
@@ -601,10 +686,7 @@ function registerDeleteTool(resAnno, server, authEnabled) {
                 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;
+            keys[k] = coerceKeyValue(provided, cdsType);
         }
         logger_1.LOGGER.debug(`Executing DELETE on ${resAnno.target} with keys`, keys);
         const tx = svc.tx({ user: (0, utils_1.getAccessRights)(authEnabled) });

package/lib/mcp/factory.js

@@ -34,8 +34,10 @@ function createMcpServer(config, annotations) {
     }
     logger_1.LOGGER.debug("Annotations found for server: ", annotations);
     const authEnabled = (0, utils_1.isAuthEnabled)(config.auth);
-    // Always register discovery tool for better model planning
-    (0, describe_model_1.registerDescribeModelTool)(server);
+    // Always register discovery tool for better model planning unless specifically turned off in configuration
+    if (config.enable_model_description) {
+        (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) {

package/lib/mcp/utils.js

@@ -31,17 +31,17 @@ function determineMcpParameterType(cdsType, key, target) {
         case "Timestamp":
             return zod_1.z.coerce.date();
         case "Integer":
-            return zod_1.z.number();
+            return zod_1.z.number().int();
         case "Int16":
-            return zod_1.z.number();
+            return zod_1.z.number().int();
         case "Int32":
-            return zod_1.z.number();
+            return zod_1.z.number().int();
         case "Int64":
-            return zod_1.z.number();
+            return zod_1.z.union([zod_1.z.string(), zod_1.z.number().int()]).transform(String);
         case "UInt8":
-            return zod_1.z.number();
+            return zod_1.z.number().int().min(0);
         case "Decimal":
-            return zod_1.z.number();
+            return zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).transform(String);
         case "Double":
             return zod_1.z.number();
         case "Boolean":
@@ -67,17 +67,17 @@ function determineMcpParameterType(cdsType, key, target) {
         case "UUIDArray":
             return zod_1.z.array(zod_1.z.string());
         case "IntegerArray":
-            return zod_1.z.array(zod_1.z.number());
+            return zod_1.z.array(zod_1.z.number().int());
         case "Int16Array":
-            return zod_1.z.array(zod_1.z.number());
+            return zod_1.z.array(zod_1.z.number().int());
         case "Int32Array":
-            return zod_1.z.array(zod_1.z.number());
+            return zod_1.z.array(zod_1.z.number().int());
         case "Int64Array":
-            return zod_1.z.array(zod_1.z.number());
+            return zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.number().int()]).transform(String));
         case "UInt8Array":
-            return zod_1.z.array(zod_1.z.number());
+            return zod_1.z.array(zod_1.z.number().int().min(0));
         case "DecimalArray":
-            return zod_1.z.array(zod_1.z.number());
+            return zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).transform(String));
         case "BooleanArray":
             return zod_1.z.array(zod_1.z.boolean());
         case "DoubleArray":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavdi/cap-mcp",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "MCP Plugin for CAP",
   "keywords": [
     "MCP",