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

package/lib/mcp/entity-tools.js

@@ -61,6 +61,45 @@ 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)
+// Map OData operators to CDS/SQL operators for better performance and readability
+const ODATA_TO_CDS_OPERATORS = new Map([
+    ["eq", "="],
+    ["ne", "!="],
+    ["gt", ">"],
+    ["ge", ">="],
+    ["lt", "<"],
+    ["le", "<="],
+]);
+/**
+ * Builds enhanced query tool description with field types and association examples
+ */
+function buildEnhancedQueryDescription(resAnno) {
+    const associations = Array.from(resAnno.properties.entries())
+        .filter(([, cdsType]) => String(cdsType).toLowerCase().includes("association"))
+        .map(([name]) => `${name}_ID`);
+    const baseDesc = `Query ${resAnno.target} with structured filters, select, orderby, top/skip.`;
+    const assocHint = associations.length > 0
+        ? ` IMPORTANT: For associations, always use foreign key fields (${associations.join(", ")}) - never use association names directly.`
+        : "";
+    return baseDesc + assocHint;
+}
+/**
+ * Builds field documentation for schema descriptions
+ */
+function buildFieldDocumentation(resAnno) {
+    const docs = [];
+    for (const [propName, cdsType] of resAnno.properties.entries()) {
+        const isAssociation = String(cdsType).toLowerCase().includes("association");
+        if (isAssociation) {
+            docs.push(`${propName}(association: compare by key value)`);
+            docs.push(`${propName}_ID(foreign key for ${propName})`);
+        }
+        else {
+            docs.push(`${propName}(${String(cdsType).toLowerCase()})`);
+        }
+    }
+    return docs.join(", ");
+}
 /**
  * Registers CRUD-like MCP tools for an annotated entity (resource).
  * Modes can be controlled globally via configuration and per-entity via @mcp.wrap.
@@ -115,9 +154,27 @@ function nameFor(service, entity, suffix) {
 function registerQueryTool(resAnno, server, authEnabled) {
     const toolName = nameFor(resAnno.serviceName, resAnno.target, "query");
     // Structured input schema for queries with guard for empty property lists
-    const propKeys = Array.from(resAnno.properties.keys());
-    const fieldEnum = (propKeys.length
-        ? zod_1.z.enum(propKeys)
+    const allKeys = Array.from(resAnno.properties.keys());
+    const scalarKeys = Array.from(resAnno.properties.entries())
+        .filter(([, cdsType]) => !String(cdsType).toLowerCase().includes("association"))
+        .map(([name]) => name);
+    // Add foreign key fields for associations to scalar keys for select/orderby
+    for (const [propName, cdsType] of resAnno.properties.entries()) {
+        const isAssociation = String(cdsType).toLowerCase().includes("association");
+        if (isAssociation) {
+            scalarKeys.push(`${propName}_ID`);
+        }
+    }
+    // Build where field enum: use same fields as select (scalar + foreign keys)
+    // This ensures consistency - what you can select, you can filter by
+    const whereKeys = [...scalarKeys];
+    const whereFieldEnum = (whereKeys.length
+        ? zod_1.z.enum(whereKeys)
+        : zod_1.z
+            .enum(["__dummy__"])
+            .transform(() => "__dummy__"));
+    const selectFieldEnum = (scalarKeys.length
+        ? zod_1.z.enum(scalarKeys)
         : zod_1.z
             .enum(["__dummy__"])
             .transform(() => "__dummy__"));
@@ -131,16 +188,21 @@ function registerQueryTool(resAnno, server, authEnabled) {
             .default(25)
             .describe("Rows (default 25)"),
         skip: zod_1.z.number().int().min(0).default(0).describe("Offset"),
-        select: zod_1.z.array(fieldEnum).optional(),
+        select: zod_1.z
+            .array(selectFieldEnum)
+            .optional()
+            .transform((val) => val && val.length > 0 ? val : undefined)
+            .describe(`Select/orderby allow only scalar fields: ${scalarKeys.join(", ")}`),
         orderby: zod_1.z
             .array(zod_1.z.object({
-            field: fieldEnum,
+            field: selectFieldEnum,
             dir: zod_1.z.enum(["asc", "desc"]).default("asc"),
         }))
-            .optional(),
+            .optional()
+            .transform((val) => val && val.length > 0 ? val : undefined),
         where: zod_1.z
             .array(zod_1.z.object({
-            field: fieldEnum,
+            field: whereFieldEnum.describe(`FILTERABLE FIELDS: ${scalarKeys.join(", ")}. For associations use foreign key (author_ID), NOT association name (author).`),
             op: zod_1.z.enum([
                 "eq",
                 "ne",
@@ -160,15 +222,17 @@ function registerQueryTool(resAnno, server, authEnabled) {
                 zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.number()])),
             ]),
         }))
-            .optional(),
+            .optional()
+            .transform((val) => val && val.length > 0 ? val : undefined),
         q: zod_1.z.string().optional().describe("Quick text search"),
         return: zod_1.z.enum(["rows", "count", "aggregate"]).default("rows").optional(),
         aggregate: zod_1.z
             .array(zod_1.z.object({
-            field: fieldEnum,
+            field: selectFieldEnum,
             fn: zod_1.z.enum(["sum", "avg", "min", "max", "count"]),
         }))
-            .optional(),
+            .optional()
+            .transform((val) => (val && val.length > 0 ? val : undefined)),
         explain: zod_1.z.boolean().optional(),
     })
         .strict();
@@ -184,7 +248,8 @@ function registerQueryTool(resAnno, server, authEnabled) {
         explain: inputZod.shape.explain,
     };
     const hint = resAnno.wrap?.hint ? ` Hint: ${resAnno.wrap?.hint}` : "";
-    const desc = `List ${resAnno.target}. Use structured filters (where), top/skip/orderby/select. For fields & examples call cap_describe_model.${hint}`;
+    const desc = `${buildEnhancedQueryDescription(resAnno)} CRITICAL: Use foreign key fields (e.g., author_ID) for associations - association names (e.g., author) won't work in filters.` +
+        hint;
     const queryHandler = async (rawArgs) => {
         const parsed = inputZod.safeParse(rawArgs);
         if (!parsed.success) {
@@ -203,7 +268,7 @@ function registerQueryTool(resAnno, server, authEnabled) {
         }
         let q;
         try {
-            q = buildQuery(CDS, args, resAnno, propKeys);
+            q = buildQuery(CDS, args, resAnno, allKeys);
         }
         catch (e) {
             return (0, utils_2.toolError)("FILTER_PARSE_ERROR", e?.message || String(e));
@@ -564,8 +629,9 @@ function buildQuery(CDS, args, resAnno, propKeys) {
     let qy = SELECT.from(resAnno.target).limit(limitTop, limitSkip);
     if ((propKeys?.length ?? 0) === 0)
         return qy;
-    if (args.select?.length)
+    if (args.select?.length) {
         qy = qy.columns(...args.select);
+    }
     if (args.orderby?.length) {
         // Map to CQN-compatible order by fragments
         const orderFragments = args.orderby.map((o) => `${o.field} ${o.dir}`);
@@ -575,29 +641,40 @@ function buildQuery(CDS, args, resAnno, propKeys) {
         const ands = [];
         if (args.q) {
             const textFields = Array.from(resAnno.properties.keys()).filter((k) => /string/i.test(String(resAnno.properties.get(k))));
-            const ors = textFields.map((f) => CDS.parse.expr(`contains(${f}, '${String(args.q).replace(/'/g, "''")}')`));
-            if (ors.length)
-                ands.push(CDS.parse.expr(ors.map((x) => `(${x})`).join(" or ")));
+            const escaped = String(args.q).replace(/'/g, "''");
+            const ors = textFields.map((f) => `contains(${f}, '${escaped}')`);
+            if (ors.length) {
+                const orExpr = ors.map((x) => `(${x})`).join(" or ");
+                ands.push(CDS.parse.expr(orExpr));
+            }
         }
         for (const c of args.where || []) {
             const { field, op, value } = c;
+            // Field names are now consistent - use them directly
+            const actualField = field;
             if (op === "in" && Array.isArray(value)) {
                 const list = value
                     .map((v) => typeof v === "string" ? `'${v.replace(/'/g, "''")}'` : String(v))
                     .join(",");
-                ands.push(CDS.parse.expr(`${field} in (${list})`));
+                ands.push(CDS.parse.expr(`${actualField} in (${list})`));
                 continue;
             }
             const lit = typeof value === "string"
                 ? `'${String(value).replace(/'/g, "''")}'`
                 : String(value);
+            // Map OData operators to CDS/SQL operators
+            const cdsOp = ODATA_TO_CDS_OPERATORS.get(op) ?? op;
             const expr = ["contains", "startswith", "endswith"].includes(op)
-                ? `${op}(${field}, ${lit})`
-                : `${field} ${op} ${lit}`;
+                ? `${op}(${actualField}, ${lit})`
+                : `${actualField} ${cdsOp} ${lit}`;
             ands.push(CDS.parse.expr(expr));
         }
-        if (ands.length)
-            qy = qy.where(ands);
+        if (ands.length) {
+            // Apply each condition individually - CDS will AND them together
+            for (const condition of ands) {
+                qy = qy.where(condition);
+            }
+        }
     }
     return qy;
 }

package/lib/mcp/tools.js

@@ -6,6 +6,7 @@ const logger_1 = require("../logger");
 const constants_1 = require("./constants");
 const zod_1 = require("zod");
 const utils_2 = require("../auth/utils");
+const elicited_input_1 = require("./elicited-input");
 /* @ts-ignore */
 const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
 /**
@@ -37,7 +38,12 @@ function assignBoundOperation(params, model, server, authEnabled) {
         throw new Error("Bound operation cannot be assigned to tool list, missing keys");
     }
     const keys = buildToolParameters(model.keyTypeMap);
-    const inputSchema = buildZodSchema({ ...keys, ...params });
+    const useElicitInput = (0, elicited_input_1.isElicitInput)(model.elicits);
+    const inputSchema = buildZodSchema({
+        ...keys,
+        ...(useElicitInput ? {} : params),
+    });
+    const elicitationRequests = (0, elicited_input_1.constructElicitationFunctions)(model, params);
     server.registerTool(model.name, {
         title: model.name,
         description: model.description,
@@ -69,11 +75,15 @@ function assignBoundOperation(params, model, server, authEnabled) {
                 continue;
             operationInput[k] = v;
         }
+        const elicitationResult = await (0, elicited_input_1.handleElicitationRequests)(elicitationRequests, server);
+        if (elicitationResult?.earlyResponse) {
+            return elicitationResult.earlyResponse;
+        }
         const accessRights = (0, utils_2.getAccessRights)(authEnabled);
         const response = await service.tx({ user: accessRights }).send({
             event: model.target,
             entity: model.entityKey,
-            data: operationInput,
+            data: elicitationResult?.data ?? operationInput,
             params: [operationKeys],
         });
         return (0, utils_1.asMcpResult)(response);
@@ -87,7 +97,9 @@ function assignBoundOperation(params, model, server, authEnabled) {
  * @param server - MCP server instance to register with
  */
 function assignUnboundOperation(params, model, server, authEnabled) {
-    const inputSchema = buildZodSchema(params);
+    const useElicitInput = (0, elicited_input_1.isElicitInput)(model.elicits);
+    const inputSchema = buildZodSchema(useElicitInput ? {} : params);
+    const elicitationRequests = (0, elicited_input_1.constructElicitationFunctions)(model, params);
     server.registerTool(model.name, {
         title: model.name,
         description: model.description,
@@ -109,10 +121,14 @@ function assignUnboundOperation(params, model, server, authEnabled) {
                 ],
             };
         }
+        const elicitationResult = await (0, elicited_input_1.handleElicitationRequests)(elicitationRequests, server);
+        if (elicitationResult?.earlyResponse) {
+            return elicitationResult.earlyResponse;
+        }
         const accessRights = (0, utils_2.getAccessRights)(authEnabled);
         const response = await service
             .tx({ user: accessRights })
-            .send(model.target, args);
+            .send(model.target, elicitationResult?.data ?? args);
         return (0, utils_1.asMcpResult)(response);
     });
 }
@@ -130,27 +146,6 @@ function buildToolParameters(params) {
     }
     return result;
 }
-/**
- * Converts a value to a string representation suitable for MCP responses
- * Handles objects and arrays by JSON stringifying them instead of using String()
- * @param value - The value to convert to string
- * @returns String representation of the value
- */
-function formatResponseValue(value) {
-    if (value === null || value === undefined) {
-        return String(value);
-    }
-    if (typeof value === "object") {
-        try {
-            return JSON.stringify(value, null, 2);
-        }
-        catch (error) {
-            // Fallback to String() if JSON.stringify fails (e.g., circular references)
-            return String(value);
-        }
-    }
-    return String(value);
-}
 /**
  * Constructs a complete Zod schema object for MCP tool input validation
  * @param params - Record of parameter names to Zod schema types

package/lib/mcp/utils.js

@@ -18,6 +18,8 @@ function determineMcpParameterType(cdsType) {
             return zod_1.z.string();
         case "Integer":
             return zod_1.z.number();
+        case "Boolean":
+            return zod_1.z.boolean();
         default:
             return zod_1.z.string();
     }

package/lib/mcp.js

@@ -40,9 +40,7 @@ class McpPlugin {
         logger_1.LOGGER.debug("Event received for 'bootstrap'");
         this.expressApp = app;
         this.expressApp.use("/mcp", express_1.default.json());
-        // To make it more safe, if there is a mispelling we will always implement auth
-        // Users will have to explicitly write none
-        if (this.config.auth !== "none") {
+        if (this.config.auth === "inherit") {
             (0, utils_2.registerAuthMiddleware)(this.expressApp);
         }
         await this.registerApiEndpoints();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavdi/cap-mcp",
-  "version": "0.9.9-alpha.3",
+  "version": "0.10.0",
   "description": "MCP Pluging for CAP",
   "keywords": [
     "MCP",
@@ -41,7 +41,7 @@
     "express": "^4"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.17.4",
+    "@modelcontextprotocol/sdk": "^1.17.3",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5"
   },

package/lib/annotations.js

@@ -1,257 +0,0 @@
-"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

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

package/lib/auth/mock.js

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

package/lib/auth/types.js

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