@gavdi/cap-mcp 1.2.2 → 1.3.1

package/README.md

@@ -88,6 +88,8 @@ service CatalogService {
 }
 ```
 
+> **Note**: The `@mcp.wrap.hint` annotation provides operation-level guidance, while `@mcp.hint` on individual elements provides field-level descriptions. Both work together to give AI agents comprehensive context.
+
 ### Step 4: Start Your Application
 
 ```bash
@@ -202,6 +204,63 @@ Example:
   };
 ```
 
+For field-level descriptions within these tools, see [Element Hints with @mcp.hint](#element-hints-with-mcphint).
+
+### Omitting Sensitive Fields
+
+Protect sensitive data by excluding specific fields from MCP responses using the `@mcp.omit` annotation:
+
+```cds
+namespace my.bookshop;
+
+entity Books {
+  key ID            : Integer;
+      title         : String;
+      stock         : Integer;
+      author        : Association to Authors;
+      secretMessage : String  @mcp.omit;  // Hidden from all MCP responses
+}
+
+entity Users {
+  key ID             : Integer;
+      username       : String;
+      email          : String;
+      darkestSecret  : String  @mcp.omit;      // Never exposed to MCP clients
+      ssn            : String  @mcp.omit;      // Protected sensitive data
+      lastLogin      : DateTime;
+}
+```
+
+**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;
+      name        : String;
+      price       : Decimal;
+      costPrice   : Decimal  @mcp.omit;    // Hide internal pricing
+      createdAt   : DateTime @Core.Computed; // Auto-generated, not writable
+      updatedAt   : DateTime @Core.Computed; // Auto-generated, not writable
+      secretNote  : String   @mcp.omit;    // Hide from MCP
+}
+```
+
 ### Tool Annotations
 
 Convert CAP functions and actions into executable AI tools:
@@ -272,6 +331,112 @@ function getBooksByAuthor(authorName: String) returns array of String;
 - **User Actions**: Accept, decline, or cancel the elicitation request
 - **Early Exit**: Tools return appropriate messages if declined or cancelled
 
+### Element Hints with @mcp.hint
+
+Provide contextual descriptions for individual properties and parameters using the `@mcp.hint` annotation. These hints help AI agents better understand the purpose, constraints, and expected values for specific fields.
+
+#### 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';
+      title : String;
+      stock : Integer @mcp.hint: 'The amount of books currently on store shelves';
+}
+```
+
+**Array Elements**
+```cds
+entity Authors {
+  key ID          : Integer;
+      name        : String @mcp.hint: 'Full name of the author';
+      nominations : array of String @mcp.hint: 'Awards that the author has been nominated for';
+}
+```
+
+**Function/Action Parameters**
+```cds
+@mcp: {
+  name       : 'books-by-author',
+  description: 'Gets a list of books made by the author',
+  tool       : true
+}
+function getBooksByAuthor(
+  authorName : String @mcp.hint: 'Full name of the author you want to get the books of'
+) returns array of String;
+```
+
+**Complex Type Fields**
+```cds
+type TValidQuantities {
+  positiveOnly : Integer @mcp.hint: 'Only takes in positive numbers, i.e. no negative values such as -1'
+};
+```
+
+#### 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
+
+#### Example: Enhanced Tool Experience
+
+Without `@mcp.hint`:
+```json
+{
+  "tool": "CatalogService_Books_create",
+  "parameters": {
+    "ID": { "type": "integer" },
+    "stock": { "type": "integer" }
+  }
+}
+```
+
+With `@mcp.hint`:
+```json
+{
+  "tool": "CatalogService_Books_create",
+  "parameters": {
+    "ID": {
+      "type": "integer",
+      "description": "Must be a unique number not already in the system"
+    },
+    "stock": {
+      "type": "integer",
+      "description": "The amount of books currently on store shelves"
+    }
+  }
+}
+```
+
+#### 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
+   - ❌ Bad: `stock: Integer @mcp.hint: 'Stock value'`
+   - ✅ Good: `stock: Integer @mcp.hint: 'Current inventory count across all warehouses'`
+
+#### Technical Notes
+
+- Hints are parsed at model load time and stored in the `propertyHints` map
+- Hints work with both simple types and complex nested types
+- Hints are accessible in both resource queries and tool executions
+- Array element hints apply to the array items, not the array itself
+
 ### Prompt Templates
 
 Define reusable AI prompt templates:

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_MAPPING = exports.MCP_ANNOTATION_KEY = void 0;
+exports.MCP_OMIT_PROP_KEY = exports.MCP_HINT_ELEMENT = exports.DEFAULT_ALL_RESOURCE_OPTIONS = exports.MCP_ANNOTATION_MAPPING = exports.MCP_ANNOTATION_KEY = void 0;
 /**
  * MCP annotation constants and default configurations
  * Defines the standard annotation keys and default values used throughout the plugin
@@ -44,3 +44,11 @@ exports.DEFAULT_ALL_RESOURCE_OPTIONS = new Set([
     "skip",
     "select",
 ]);
+/**
+ * Hint key for annotations made on specific properties/elements
+ */
+exports.MCP_HINT_ELEMENT = "@mcp.hint";
+/**
+ * MCP omit property annotation key
+ */
+exports.MCP_OMIT_PROP_KEY = "@mcp.omit";

package/lib/annotations/parser.js

@@ -133,9 +133,12 @@ function constructResourceAnnotation(serviceName, target, annotations, definitio
     const computedFields = new Set(Object.entries(model.definitions?.[entityTarget].elements ?? {})
         .filter(([_, v]) => new Map(Object.entries(v).map(([key, value]) => [key.toLowerCase(), value])).get("@core.computed"))
         .map(([k, _]) => k));
-    const { properties, resourceKeys } = (0, utils_1.parseResourceElements)(definition, model);
+    const omittedFields = new Set(Object.entries(model.definitions?.[entityTarget].elements ?? {})
+        .filter(([_, v]) => v[constants_1.MCP_OMIT_PROP_KEY])
+        .map(([k, _]) => k));
+    const { properties, resourceKeys, propertyHints } = (0, utils_1.parseResourceElements)(definition, model);
     const restrictions = (0, utils_1.parseCdsRestrictions)(annotations.restrict, annotations.requires);
-    return new structures_1.McpResourceAnnotation(annotations.name, annotations.description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, annotations.wrap, restrictions, computedFields);
+    return new structures_1.McpResourceAnnotation(annotations.name, annotations.description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, annotations.wrap, restrictions, computedFields, propertyHints, omittedFields);
 }
 /**
  * Constructs a tool annotation from parsed annotation data
@@ -149,9 +152,9 @@ function constructResourceAnnotation(serviceName, target, annotations, definitio
 function constructToolAnnotation(model, serviceName, target, annotations, entityKey, keyParams) {
     if (!(0, utils_1.isValidToolAnnotation)(annotations))
         return undefined;
-    const { parameters, operationKind } = (0, utils_1.parseOperationElements)(annotations, model);
+    const { parameters, operationKind, propertyHints } = (0, utils_1.parseOperationElements)(annotations, model);
     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, annotations.elicit);
+    return new structures_1.McpToolAnnotation(annotations.name, annotations.description, target, serviceName, parameters, entityKey, operationKind, keyParams, restrictions, annotations.elicit, propertyHints);
 }
 /**
  * Constructs a prompt annotation from parsed annotation data

package/lib/annotations/structures.js

@@ -16,6 +16,8 @@ class McpAnnotation {
     _serviceName;
     /** Auth roles by providing CDS that is required for use */
     _restrictions;
+    /** Property hints to be used for inputs */
+    _propertyHints;
     /**
      * Creates a new MCP annotation instance
      * @param name - Unique identifier for this annotation
@@ -24,12 +26,13 @@ class McpAnnotation {
      * @param serviceName - Name of the associated CAP service
      * @param restrictions - Roles required for the given annotation
      */
-    constructor(name, description, target, serviceName, restrictions) {
+    constructor(name, description, target, serviceName, restrictions, propertyHints) {
         this._name = name;
         this._description = description;
         this._target = target;
         this._serviceName = serviceName;
         this._restrictions = restrictions;
+        this._propertyHints = propertyHints;
     }
     /**
      * Gets the unique name identifier for this annotation
@@ -67,6 +70,13 @@ class McpAnnotation {
     get restrictions() {
         return this._restrictions;
     }
+    /**
+     * Gets a map of possible property hints to be used for resource/tool properties.
+     * @returns Map of property hints
+     */
+    get propertyHints() {
+        return this._propertyHints;
+    }
 }
 exports.McpAnnotation = McpAnnotation;
 /**
@@ -86,6 +96,8 @@ class McpResourceAnnotation extends McpAnnotation {
     _foreignKeys;
     /** Set of computed field names */
     _computedFields;
+    /** List of omitted fields */
+    _omittedFields;
     /**
      * Creates a new MCP resource annotation
      * @param name - Unique identifier for this resource
@@ -99,15 +111,18 @@ class McpResourceAnnotation extends McpAnnotation {
      * @param wrap - Wrap usage
      * @param restrictions - Optional restrictions based on CDS roles
      * @param computedFields - Optional set of fields that are computed and should be ignored in create scenarios
+     * @param propertyHints - Optional map of hints for specific properties on resource
+     * @param omittedFields - Optional set of fields that should be omitted from MCP entity
      */
-    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, wrap, restrictions, computedFields) {
-        super(name, description, target, serviceName, restrictions ?? []);
+    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys, foreignKeys, wrap, restrictions, computedFields, propertyHints, omittedFields) {
+        super(name, description, target, serviceName, restrictions ?? [], propertyHints ?? new Map());
         this._functionalities = functionalities;
         this._properties = properties;
         this._resourceKeys = resourceKeys;
         this._wrap = wrap;
         this._foreignKeys = foreignKeys;
         this._computedFields = computedFields;
+        this._omittedFields = omittedFields;
     }
     /**
      * Gets the set of enabled OData query functionalities
@@ -149,6 +164,12 @@ class McpResourceAnnotation extends McpAnnotation {
     get computedFields() {
         return this._computedFields;
     }
+    /**
+     * Gets a set of fields/elements of the resource that should be omitted if any
+     */
+    get omittedFields() {
+        return this._omittedFields;
+    }
 }
 exports.McpResourceAnnotation = McpResourceAnnotation;
 /**
@@ -178,9 +199,10 @@ class McpToolAnnotation extends McpAnnotation {
      * @param keyTypeMap - Optional map of key fields to types for bound operations
      * @param restrictions - Optional restrictions based on CDS roles
      * @param elicits - Optional elicited input requirement
+     * @param propertyHints - Optional map of property hints for tool inputs
      */
-    constructor(name, description, operation, serviceName, parameters, entityKey, operationKind, keyTypeMap, restrictions, elicits) {
-        super(name, description, operation, serviceName, restrictions ?? []);
+    constructor(name, description, operation, serviceName, parameters, entityKey, operationKind, keyTypeMap, restrictions, elicits, propertyHints) {
+        super(name, description, operation, serviceName, restrictions ?? [], propertyHints ?? new Map());
         this._parameters = parameters;
         this._entityKey = entityKey;
         this._operationKind = operationKind;
@@ -239,7 +261,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, [], new Map());
         this._prompts = prompts;
     }
     /**

package/lib/annotations/utils.js

@@ -167,6 +167,7 @@ function determineResourceOptions(annotations) {
 function parseResourceElements(definition, model) {
     const properties = new Map();
     const resourceKeys = new Map();
+    const propertyHints = new Map();
     const parseParam = (k, v, suffix) => {
         let result = "";
         if (typeof v.type !== "string") {
@@ -176,12 +177,18 @@ function parseResourceElements(definition, model) {
         else {
             result = `${v.type.replace("cds.", "")}${suffix ?? ""}`;
         }
+        if (v[constants_1.MCP_HINT_ELEMENT]) {
+            propertyHints.set(k, v[constants_1.MCP_HINT_ELEMENT]);
+        }
         properties?.set(k, result);
         return result;
     };
     for (const [k, v] of Object.entries(definition.elements || {})) {
         if (v.items) {
             const result = parseParam(k, v.items, "Array");
+            if (v[constants_1.MCP_HINT_ELEMENT]) {
+                propertyHints.set(k, v[constants_1.MCP_HINT_ELEMENT]);
+            }
             if (!v.key)
                 continue;
             resourceKeys.set(k, result);
@@ -195,6 +202,7 @@ function parseResourceElements(definition, model) {
     return {
         properties,
         resourceKeys,
+        propertyHints,
     };
 }
 /**
@@ -204,12 +212,16 @@ function parseResourceElements(definition, model) {
  */
 function parseOperationElements(annotations, model) {
     let parameters;
+    const propertyHints = new Map();
     const parseParam = (k, v, suffix) => {
         if (typeof v.type !== "string") {
             const referencedType = parseTypedReference(v.type, model);
             parameters?.set(k, `${referencedType}${suffix ?? ""}`);
             return;
         }
+        if (v[constants_1.MCP_HINT_ELEMENT]) {
+            propertyHints.set(k, v[constants_1.MCP_HINT_ELEMENT]);
+        }
         parameters?.set(k, `${v.type.replace("cds.", "")}${suffix ?? ""}`);
     };
     const params = annotations.definition["params"];
@@ -218,6 +230,9 @@ function parseOperationElements(annotations, model) {
         for (const [k, v] of Object.entries(params)) {
             if (v.items) {
                 parseParam(k, v.items, "Array");
+                if (v[constants_1.MCP_HINT_ELEMENT]) {
+                    propertyHints.set(k, v[constants_1.MCP_HINT_ELEMENT]);
+                }
                 continue;
             }
             parseParam(k, v);
@@ -226,6 +241,7 @@ function parseOperationElements(annotations, model) {
     return {
         parameters,
         operationKind: annotations.definition.kind,
+        propertyHints,
     };
 }
 /**

package/lib/mcp/entity-tools.js

@@ -139,7 +139,8 @@ function registerQueryTool(resAnno, server, authEnabled) {
     // 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())
-        .filter(([, cdsType]) => !String(cdsType).toLowerCase().includes("association"))
+        .filter(([k, cdsType]) => !String(cdsType).toLowerCase().includes("association") &&
+        !resAnno.omittedFields?.has(k))
         .map(([name]) => name);
     // Build where field enum: use same fields as select (scalar + foreign keys)
     // This ensures consistency - what you can select, you can filter by
@@ -252,8 +253,9 @@ function registerQueryTool(resAnno, server, authEnabled) {
         try {
             const t0 = Date.now();
             const response = await withTimeout(executeQuery(CDS, svc, args, q), TIMEOUT_MS, toolName);
+            const result = response?.map((obj) => (0, utils_2.applyOmissionFilter)(obj, resAnno));
             logger_1.LOGGER.debug(`[EXECUTION TIME] Query tool completed: ${toolName} in ${Date.now() - t0}ms`, { resultKind: args.return ?? "rows" });
-            return (0, utils_2.asMcpResult)(args.explain ? { data: response, plan: undefined } : response);
+            return (0, utils_2.asMcpResult)(args.explain ? { data: result, plan: undefined } : result);
         }
         catch (error) {
             const msg = `QUERY_FAILED: ${error?.message || String(error)}`;
@@ -271,7 +273,7 @@ function registerGetTool(resAnno, server, authEnabled) {
     const toolName = nameFor(resAnno.serviceName, resAnno.target, "get");
     const inputSchema = {};
     for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
-        inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}`);
+        inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}. ${resAnno.propertyHints.get(k) ?? ""}`);
     }
     const keyList = Array.from(resAnno.resourceKeys.keys()).join(", ");
     const hint = constructHintMessage(resAnno, "get");
@@ -323,9 +325,10 @@ function registerGetTool(resAnno, server, authEnabled) {
         }
         logger_1.LOGGER.debug(`Executing READ on ${resAnno.target} with keys`, keys);
         try {
-            const response = await withTimeout(svc.run(svc.read(resAnno.target, keys)), TIMEOUT_MS, `${toolName}`);
+            let response = await withTimeout(svc.run(svc.read(resAnno.target, keys)), TIMEOUT_MS, `${toolName}`);
             logger_1.LOGGER.debug(`[EXECUTION TIME] Get tool completed: ${toolName} in ${Date.now() - startTime}ms`, { found: !!response });
-            return (0, utils_2.asMcpResult)(response ?? null);
+            const result = (0, utils_2.applyOmissionFilter)(response, resAnno);
+            return (0, utils_2.asMcpResult)(result ?? null);
         }
         catch (error) {
             const msg = `GET_FAILED: ${error?.message || String(error)}`;
@@ -352,8 +355,8 @@ function registerCreateTool(resAnno, server, authEnabled) {
         inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType, propName, `${resAnno.serviceName}.${resAnno.target}`)
             .optional()
             .describe(resAnno.foreignKeys.has(propName)
-            ? `Foreign key to ${resAnno.foreignKeys.get(propName)} on ${propName}`
-            : `Field ${propName}`);
+            ? `Foreign key to ${resAnno.foreignKeys.get(propName)} on ${propName}. ${resAnno.propertyHints.get(propName) ?? ""}`
+            : `Field ${propName}. ${resAnno.propertyHints.get(propName) ?? ""}`);
     }
     const hint = constructHintMessage(resAnno, "create");
     const desc = `Resource description: ${resAnno.description}. Create a new ${resAnno.target}. Provide fields; service applies defaults.${hint}`;
@@ -400,7 +403,8 @@ function registerCreateTool(resAnno, server, authEnabled) {
                 await tx.commit();
             }
             catch { }
-            return (0, utils_2.asMcpResult)(response ?? {});
+            const result = (0, utils_2.applyOmissionFilter)(response, resAnno);
+            return (0, utils_2.asMcpResult)(result ?? {});
         }
         catch (error) {
             try {
@@ -426,7 +430,7 @@ function registerUpdateTool(resAnno, server, authEnabled) {
     const inputSchema = {};
     // Keys required
     for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
-        inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}`);
+        inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}. ${resAnno.propertyHints.get(k) ?? ""}`);
     }
     // Other fields optional
     for (const [propName, cdsType] of resAnno.properties.entries()) {
@@ -441,8 +445,8 @@ function registerUpdateTool(resAnno, server, authEnabled) {
         inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType, propName, `${resAnno.serviceName}.${resAnno.target}`)
             .optional()
             .describe(resAnno.foreignKeys.has(propName)
-            ? `Foreign key to ${resAnno.foreignKeys.get(propName)} on ${propName}`
-            : `Field ${propName}`);
+            ? `Foreign key to ${resAnno.foreignKeys.get(propName)} on ${propName}. ${resAnno.propertyHints.get(propName) ?? ""}`
+            : `Field ${propName}. ${resAnno.propertyHints.get(propName) ?? ""}`);
     }
     const keyList = Array.from(resAnno.resourceKeys.keys()).join(", ");
     const hint = constructHintMessage(resAnno, "update");
@@ -505,7 +509,8 @@ function registerUpdateTool(resAnno, server, authEnabled) {
                 await tx.commit();
             }
             catch { }
-            return (0, utils_2.asMcpResult)(response ?? {});
+            const result = (0, utils_2.applyOmissionFilter)(response, resAnno);
+            return (0, utils_2.asMcpResult)(result ?? {});
         }
         catch (error) {
             try {
@@ -531,7 +536,7 @@ function registerDeleteTool(resAnno, server, authEnabled) {
     const inputSchema = {};
     // Keys required for deletion
     for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
-        inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}`);
+        inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}. ${resAnno.propertyHints.get(k) ?? ""}`);
     }
     const keyList = Array.from(resAnno.resourceKeys.keys()).join(", ");
     const hint = constructHintMessage(resAnno, "delete");

package/lib/mcp/resources.js

@@ -101,11 +101,12 @@ function assignResourceToServer(model, server, authEnabled) {
         try {
             const accessRights = (0, utils_2.getAccessRights)(authEnabled);
             const response = await service.tx({ user: accessRights }).run(query);
+            const result = response?.map((el) => (0, utils_1.applyOmissionFilter)(el, model));
             return {
                 contents: [
                     {
                         uri: uri.href,
-                        text: response ? JSON.stringify(response) : "",
+                        text: result ? JSON.stringify(result) : "",
                     },
                 ],
             };
@@ -141,11 +142,12 @@ function registerStaticResource(model, server, authEnabled) {
                 : 100);
             const accessRights = (0, utils_2.getAccessRights)(authEnabled);
             const response = await service.tx({ user: accessRights }).run(query);
+            const result = response?.map((el) => (0, utils_1.applyOmissionFilter)(el, model));
             return {
                 contents: [
                     {
                         uri: uri.href,
-                        text: response ? JSON.stringify(response) : "",
+                        text: result ? JSON.stringify(result) : "",
                     },
                 ],
             };

package/lib/mcp/tools.js

@@ -17,7 +17,7 @@ const cds = global.cds || require("@sap/cds"); // This is a work around for miss
  */
 function assignToolToServer(model, server, authEnabled) {
     logger_1.LOGGER.debug("Adding tool", model);
-    const parameters = buildToolParameters(model.parameters);
+    const parameters = buildToolParameters(model.parameters, model.propertyHints);
     if (model.entityKey) {
         // Assign tool as bound operation
         assignBoundOperation(parameters, model, server, authEnabled);
@@ -37,7 +37,7 @@ function assignBoundOperation(params, model, server, authEnabled) {
         logger_1.LOGGER.error("Invalid tool assignment - missing key map for bound operation");
         throw new Error("Bound operation cannot be assigned to tool list, missing keys");
     }
-    const keys = buildToolParameters(model.keyTypeMap);
+    const keys = buildToolParameters(model.keyTypeMap, model.propertyHints);
     const useElicitInput = (0, elicited_input_1.isElicitInput)(model.elicits);
     const inputSchema = buildZodSchema({
         ...keys,
@@ -137,12 +137,12 @@ function assignUnboundOperation(params, model, server, authEnabled) {
  * @param params - Map of parameter names to their CDS type strings
  * @returns Record of parameter names to Zod schema types
  */
-function buildToolParameters(params) {
+function buildToolParameters(params, propertyHints) {
     if (!params || params.size <= 0)
         return {};
     const result = {};
     for (const [k, v] of params.entries()) {
-        result[k] = (0, utils_1.determineMcpParameterType)(v);
+        result[k] = (0, utils_1.determineMcpParameterType)(v)?.describe(propertyHints.get(k) ?? "");
     }
     return result;
 }

package/lib/mcp/utils.js

@@ -5,6 +5,7 @@ exports.handleMcpSessionRequest = handleMcpSessionRequest;
 exports.writeODataDescriptionForResource = writeODataDescriptionForResource;
 exports.toolError = toolError;
 exports.asMcpResult = asMcpResult;
+exports.applyOmissionFilter = applyOmissionFilter;
 const constants_1 = require("./constants");
 const zod_1 = require("zod");
 /* @ts-ignore */
@@ -116,6 +117,27 @@ function buildCompositionZodType(key, target) {
     for (const [k, v] of Object.entries(comp.elements)) {
         if (!v.type)
             continue;
+        const elementKeys = new Map(Object.keys(v).map((el) => [el.toLowerCase(), el]));
+        const isComputed = elementKeys.has("@core.computed") &&
+            v[elementKeys.get("@core.computed") ?? ""] === true;
+        if (isComputed)
+            continue;
+        // Check if this field is a foreign key to the parent entity in the composition
+        // If so, exclude it because CAP will auto-fill it during deep insert
+        const foreignKeyAnnotation = elementKeys.has("@odata.foreignkey4")
+            ? elementKeys.get("@odata.foreignkey4")
+            : null;
+        if (foreignKeyAnnotation) {
+            const associationName = v[foreignKeyAnnotation];
+            // Check if the association references the parent entity
+            if (associationName && comp.elements[associationName]) {
+                const association = comp.elements[associationName];
+                if (association.target === target) {
+                    // This FK references the parent entity, exclude it from composition schema
+                    continue;
+                }
+            }
+        }
         const parsedType = v.type.replace("cds.", "");
         if (parsedType === "Association" || parsedType === "Composition")
             continue; // We will not support nested compositions for now
@@ -229,3 +251,18 @@ function asMcpResult(payload) {
         ],
     };
 }
+/**
+ * Applies the omit rules for the resulting object based on the annotations.
+ * Creates a copy of the input object to avoid unwanted mutations.
+ * @param res
+ * @param annotations
+ * @returns object|undefined
+ */
+function applyOmissionFilter(res, annotations) {
+    if (!res)
+        return res; // We do not want to parse something that does not exist
+    else if (!annotations.omittedFields || annotations.omittedFields.size < 0) {
+        return { ...res };
+    }
+    return Object.fromEntries(Object.entries(res).filter(([k, _]) => !annotations.omittedFields?.has(k)));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gavdi/cap-mcp",
-  "version": "1.2.2",
-  "description": "MCP Pluging for CAP",
+  "version": "1.3.1",
+  "description": "MCP Plugin for CAP",
   "keywords": [
     "MCP",
     "CAP",