@gavdi/cap-mcp 0.9.4 → 0.9.7

package/lib/mcp/entity-tools.js

@@ -0,0 +1,548 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerEntityWrappers = registerEntityWrappers;
+const zod_1 = require("zod");
+const utils_1 = require("../auth/utils");
+const logger_1 = require("../logger");
+const utils_2 = require("./utils");
+/**
+ * Wraps a promise with a timeout to avoid indefinite hangs in MCP tool calls.
+ * Ensures we always either resolve within the expected time or fail gracefully.
+ */
+async function withTimeout(promise, ms, label, onTimeout) {
+    let timeoutId;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(async () => {
+                    try {
+                        await onTimeout?.();
+                    }
+                    catch { }
+                    reject(new Error(`${label} timed out after ${ms}ms`));
+                }, ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}
+/**
+ * Attempts to find a running CAP service instance for the given service name.
+ * - Checks the in-memory services registry first
+ * - Falls back to known service providers (when available)
+ * Note: We deliberately avoid creating new connections here to not duplicate contexts.
+ */
+async function resolveServiceInstance(serviceName) {
+    const CDS = global.cds;
+    // Direct lookup (both exact and lowercase variants)
+    let svc = CDS.services?.[serviceName] || CDS.services?.[serviceName.toLowerCase()];
+    if (svc)
+        return svc;
+    // Look through known service providers
+    const providers = (CDS.service && CDS.service.providers) ||
+        (CDS.services && CDS.services.providers) ||
+        [];
+    if (Array.isArray(providers)) {
+        const found = providers.find((p) => p?.definition?.name === serviceName ||
+            p?.name === serviceName ||
+            (typeof p?.path === "string" &&
+                p.path.includes(serviceName.toLowerCase())));
+        if (found)
+            return found;
+    }
+    // Last resort: connect by name
+    // Do not attempt to require/connect another cds instance; rely on app runtime only
+    return undefined;
+}
+// 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)
+/**
+ * Registers CRUD-like MCP tools for an annotated entity (resource).
+ * Modes can be controlled globally via configuration and per-entity via @mcp.wrap.
+ *
+ * Example tool names (naming is explicit for easier LLM usage):
+ *   Service_Entity_query, Service_Entity_get, Service_Entity_create, Service_Entity_update
+ */
+function registerEntityWrappers(resAnno, server, authEnabled, defaultModes) {
+    const CDS = global.cds;
+    logger_1.LOGGER.debug(`[REGISTRATION TIME] Registering entity wrappers for ${resAnno.serviceName}.${resAnno.target}, available services:`, Object.keys(CDS.services || {}));
+    const modes = resAnno.wrap?.modes ?? defaultModes;
+    if (modes.includes("query")) {
+        registerQueryTool(resAnno, server, authEnabled);
+    }
+    if (modes.includes("get") &&
+        resAnno.resourceKeys &&
+        resAnno.resourceKeys.size > 0) {
+        registerGetTool(resAnno, server, authEnabled);
+    }
+    if (modes.includes("create")) {
+        registerCreateTool(resAnno, server, authEnabled);
+    }
+    if (modes.includes("update") &&
+        resAnno.resourceKeys &&
+        resAnno.resourceKeys.size > 0) {
+        registerUpdateTool(resAnno, server, authEnabled);
+    }
+}
+/**
+ * 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
+ */
+function nameFor(service, entity, 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
+    return `${serviceName}_${entityName}_${suffix}`;
+}
+/**
+ * Registers the list/query tool for an entity.
+ * Supports select/where/orderby/top/skip and simple text search (q).
+ */
+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)
+        : zod_1.z
+            .enum(["__dummy__"])
+            .transform(() => "__dummy__"));
+    const inputZod = zod_1.z
+        .object({
+        top: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_TOP)
+            .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(),
+        orderby: zod_1.z
+            .array(zod_1.z.object({
+            field: fieldEnum,
+            dir: zod_1.z.enum(["asc", "desc"]).default("asc"),
+        }))
+            .optional(),
+        where: zod_1.z
+            .array(zod_1.z.object({
+            field: fieldEnum,
+            op: zod_1.z.enum([
+                "eq",
+                "ne",
+                "gt",
+                "ge",
+                "lt",
+                "le",
+                "contains",
+                "startswith",
+                "endswith",
+                "in",
+            ]),
+            value: zod_1.z.union([
+                zod_1.z.string(),
+                zod_1.z.number(),
+                zod_1.z.boolean(),
+                zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.number()])),
+            ]),
+        }))
+            .optional(),
+        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,
+            fn: zod_1.z.enum(["sum", "avg", "min", "max", "count"]),
+        }))
+            .optional(),
+        explain: zod_1.z.boolean().optional(),
+    })
+        .strict();
+    const inputSchema = {
+        top: inputZod.shape.top,
+        skip: inputZod.shape.skip,
+        select: inputZod.shape.select,
+        orderby: inputZod.shape.orderby,
+        where: inputZod.shape.where,
+        q: inputZod.shape.q,
+        return: inputZod.shape.return,
+        aggregate: inputZod.shape.aggregate,
+        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 queryHandler = async (rawArgs) => {
+        const parsed = inputZod.safeParse(rawArgs);
+        if (!parsed.success) {
+            return (0, utils_2.toolError)("INVALID_INPUT", "Query arguments failed validation", {
+                issues: parsed.error.issues,
+            });
+        }
+        const args = parsed.data;
+        const CDS = global.cds;
+        logger_1.LOGGER.debug(`[EXECUTION TIME] Query tool: Looking for service: ${resAnno.serviceName}, available services:`, Object.keys(CDS.services || {}));
+        const svc = await resolveServiceInstance(resAnno.serviceName);
+        if (!svc) {
+            const msg = `Service not found: ${resAnno.serviceName}. Available: ${Object.keys(CDS.services || {}).join(", ")}`;
+            logger_1.LOGGER.error(msg);
+            return (0, utils_2.toolError)("ERR_MISSING_SERVICE", msg);
+        }
+        let q;
+        try {
+            q = buildQuery(CDS, args, resAnno, propKeys);
+        }
+        catch (e) {
+            return (0, utils_2.toolError)("FILTER_PARSE_ERROR", e?.message || String(e));
+        }
+        try {
+            const t0 = Date.now();
+            const response = await withTimeout(executeQuery(CDS, svc, args, q), TIMEOUT_MS, toolName);
+            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);
+        }
+        catch (error) {
+            const msg = `QUERY_FAILED: ${error?.message || String(error)}`;
+            logger_1.LOGGER.error(msg, error);
+            return (0, utils_2.toolError)("QUERY_FAILED", msg);
+        }
+    };
+    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, queryHandler);
+}
+/**
+ * Registers the get-by-keys tool for an entity.
+ * 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 inputSchema = {};
+    for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
+        inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}`);
+    }
+    const keyList = Array.from(resAnno.resourceKeys.keys()).join(", ");
+    const hint = resAnno.wrap?.hint ? ` Hint: ${resAnno.wrap?.hint}` : "";
+    const desc = `Get one ${resAnno.target} by key(s): ${keyList}. For fields & examples call cap_describe_model.${hint}`;
+    const getHandler = async (args) => {
+        const startTime = Date.now();
+        const CDS = global.cds;
+        logger_1.LOGGER.debug(`[EXECUTION TIME] Get tool invoked: ${toolName}`, { args });
+        const svc = await resolveServiceInstance(resAnno.serviceName);
+        if (!svc) {
+            const msg = `Service not found: ${resAnno.serviceName}. Available: ${Object.keys(CDS.services || {}).join(", ")}`;
+            logger_1.LOGGER.error(msg);
+            return (0, utils_2.toolError)("ERR_MISSING_SERVICE", msg);
+        }
+        // Normalize single-key shorthand, case-insensitive keys, and value-only payloads
+        let normalizedArgs = args;
+        if (resAnno.resourceKeys.size === 1) {
+            const onlyKey = Array.from(resAnno.resourceKeys.keys())[0];
+            if (normalizedArgs == null ||
+                typeof normalizedArgs !== "object" ||
+                Array.isArray(normalizedArgs)) {
+                normalizedArgs = { [onlyKey]: normalizedArgs };
+            }
+            else if (normalizedArgs[onlyKey] === undefined &&
+                normalizedArgs.value !== undefined) {
+                normalizedArgs[onlyKey] = normalizedArgs.value;
+            }
+            else if (normalizedArgs[onlyKey] === undefined) {
+                const alt = Object.entries(normalizedArgs).find(([kk]) => String(kk).toLowerCase() === String(onlyKey).toLowerCase());
+                if (alt)
+                    normalizedArgs[onlyKey] = normalizedArgs[alt[0]];
+            }
+        }
+        const keys = {};
+        for (const [k] of resAnno.resourceKeys.entries()) {
+            let provided = normalizedArgs[k];
+            if (provided === undefined) {
+                const alt = Object.entries(normalizedArgs || {}).find(([kk]) => String(kk).toLowerCase() === String(k).toLowerCase());
+                if (alt)
+                    provided = normalizedArgs[alt[0]];
+            }
+            if (provided === undefined) {
+                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;
+        }
+        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}`);
+            logger_1.LOGGER.debug(`[EXECUTION TIME] Get tool completed: ${toolName} in ${Date.now() - startTime}ms`, { found: !!response });
+            return (0, utils_2.asMcpResult)(response ?? null);
+        }
+        catch (error) {
+            const msg = `GET_FAILED: ${error?.message || String(error)}`;
+            logger_1.LOGGER.error(msg, error);
+            return (0, utils_2.toolError)("GET_FAILED", msg);
+        }
+    };
+    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, getHandler);
+}
+/**
+ * Registers the create tool for an entity.
+ * Associations are exposed via <assoc>_ID fields for simplicity.
+ */
+function registerCreateTool(resAnno, server, authEnabled) {
+    const toolName = nameFor(resAnno.serviceName, resAnno.target, "create");
+    const inputSchema = {};
+    for (const [propName, cdsType] of resAnno.properties.entries()) {
+        const isAssociation = String(cdsType).toLowerCase().includes("association");
+        if (isAssociation) {
+            // Prefer foreign key input for associations: <assoc>_ID
+            inputSchema[`${propName}_ID`] = zod_1.z
+                .number()
+                .describe(`Foreign key for association ${propName}`)
+                .optional();
+            continue;
+        }
+        inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType)
+            .optional()
+            .describe(`Field ${propName}`);
+    }
+    const hint = resAnno.wrap?.hint ? ` Hint: ${resAnno.wrap?.hint}` : "";
+    const desc = `Create a new ${resAnno.target}. Provide fields; service applies defaults.${hint}`;
+    const createHandler = async (args) => {
+        const CDS = global.cds;
+        const { INSERT } = CDS.ql;
+        const svc = await resolveServiceInstance(resAnno.serviceName);
+        if (!svc) {
+            const msg = `Service not found: ${resAnno.serviceName}. Available: ${Object.keys(CDS.services || {}).join(", ")}`;
+            logger_1.LOGGER.error(msg);
+            return (0, utils_2.toolError)("ERR_MISSING_SERVICE", msg);
+        }
+        // Build data object from provided args, limited to known properties
+        // Normalize payload: prefer *_ID for associations and coerce numeric strings
+        const data = {};
+        for (const [propName, cdsType] of resAnno.properties.entries()) {
+            const isAssociation = String(cdsType)
+                .toLowerCase()
+                .includes("association");
+            if (isAssociation) {
+                const fkName = `${propName}_ID`;
+                if (args[fkName] !== undefined) {
+                    const val = args[fkName];
+                    data[fkName] =
+                        typeof val === "string" && /^\d+$/.test(val) ? Number(val) : val;
+                }
+                continue;
+            }
+            if (args[propName] !== undefined) {
+                const val = args[propName];
+                data[propName] =
+                    typeof val === "string" && /^\d+$/.test(val) ? Number(val) : val;
+            }
+        }
+        const tx = svc.tx({ user: (0, utils_1.getAccessRights)(authEnabled) });
+        try {
+            const response = await withTimeout(tx.run(INSERT.into(resAnno.target).entries(data)), TIMEOUT_MS, toolName, async () => {
+                try {
+                    await tx.rollback();
+                }
+                catch { }
+            });
+            try {
+                await tx.commit();
+            }
+            catch { }
+            return (0, utils_2.asMcpResult)(response ?? {});
+        }
+        catch (error) {
+            try {
+                await tx.rollback();
+            }
+            catch { }
+            const isTimeout = String(error?.message || "").includes("timed out");
+            const msg = isTimeout
+                ? `${toolName} timed out after ${TIMEOUT_MS}ms`
+                : `CREATE_FAILED: ${error?.message || String(error)}`;
+            logger_1.LOGGER.error(msg, error);
+            return (0, utils_2.toolError)(isTimeout ? "TIMEOUT" : "CREATE_FAILED", msg);
+        }
+    };
+    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, createHandler);
+}
+/**
+ * Registers the update tool for an entity.
+ * 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 inputSchema = {};
+    // Keys required
+    for (const [k, cdsType] of resAnno.resourceKeys.entries()) {
+        inputSchema[k] = (0, utils_2.determineMcpParameterType)(cdsType).describe(`Key ${k}`);
+    }
+    // Other fields optional
+    for (const [propName, cdsType] of resAnno.properties.entries()) {
+        if (resAnno.resourceKeys.has(propName))
+            continue;
+        const isAssociation = String(cdsType).toLowerCase().includes("association");
+        if (isAssociation) {
+            inputSchema[`${propName}_ID`] = zod_1.z
+                .number()
+                .describe(`Foreign key for association ${propName}`)
+                .optional();
+            continue;
+        }
+        inputSchema[propName] = (0, utils_2.determineMcpParameterType)(cdsType)
+            .optional()
+            .describe(`Field ${propName}`);
+    }
+    const keyList = Array.from(resAnno.resourceKeys.keys()).join(", ");
+    const hint = resAnno.wrap?.hint ? ` Hint: ${resAnno.wrap?.hint}` : "";
+    const desc = `Update ${resAnno.target} by key(s): ${keyList}. Provide fields to update.${hint}`;
+    const updateHandler = async (args) => {
+        const CDS = global.cds;
+        const { UPDATE } = CDS.ql;
+        const svc = await resolveServiceInstance(resAnno.serviceName);
+        if (!svc) {
+            const msg = `Service not found: ${resAnno.serviceName}. Available: ${Object.keys(CDS.services || {}).join(", ")}`;
+            logger_1.LOGGER.error(msg);
+            return (0, utils_2.toolError)("ERR_MISSING_SERVICE", msg);
+        }
+        // Extract keys and update fields
+        const keys = {};
+        for (const [k] of resAnno.resourceKeys.entries()) {
+            if (args[k] === undefined) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Missing key '${k}'` }],
+                };
+            }
+            keys[k] = args[k];
+        }
+        // Normalize updates: prefer *_ID for associations and coerce numeric strings
+        const updates = {};
+        for (const [propName, cdsType] of resAnno.properties.entries()) {
+            if (resAnno.resourceKeys.has(propName))
+                continue;
+            const isAssociation = String(cdsType)
+                .toLowerCase()
+                .includes("association");
+            if (isAssociation) {
+                const fkName = `${propName}_ID`;
+                if (args[fkName] !== undefined) {
+                    const val = args[fkName];
+                    updates[fkName] =
+                        typeof val === "string" && /^\d+$/.test(val) ? Number(val) : val;
+                }
+                continue;
+            }
+            if (args[propName] !== undefined) {
+                const val = args[propName];
+                updates[propName] =
+                    typeof val === "string" && /^\d+$/.test(val) ? Number(val) : val;
+            }
+        }
+        if (Object.keys(updates).length === 0) {
+            return (0, utils_2.toolError)("NO_FIELDS", "No fields provided to update");
+        }
+        const tx = svc.tx({ user: (0, utils_1.getAccessRights)(authEnabled) });
+        try {
+            const response = await withTimeout(tx.run(UPDATE(resAnno.target).set(updates).where(keys)), TIMEOUT_MS, toolName, async () => {
+                try {
+                    await tx.rollback();
+                }
+                catch { }
+            });
+            try {
+                await tx.commit();
+            }
+            catch { }
+            return (0, utils_2.asMcpResult)(response ?? {});
+        }
+        catch (error) {
+            try {
+                await tx.rollback();
+            }
+            catch { }
+            const isTimeout = String(error?.message || "").includes("timed out");
+            const msg = isTimeout
+                ? `${toolName} timed out after ${TIMEOUT_MS}ms`
+                : `UPDATE_FAILED: ${error?.message || String(error)}`;
+            logger_1.LOGGER.error(msg, error);
+            return (0, utils_2.toolError)(isTimeout ? "TIMEOUT" : "UPDATE_FAILED", msg);
+        }
+    };
+    server.registerTool(toolName, { title: toolName, description: desc, inputSchema }, updateHandler);
+}
+// Helper: compile structured inputs into a CDS query
+// The function translates the validated MCP input into CQN safely,
+// including a basic escape of string literals to avoid invalid syntax.
+function buildQuery(CDS, args, resAnno, propKeys) {
+    const { SELECT } = CDS.ql;
+    const limitTop = args.top ?? 25;
+    const limitSkip = args.skip ?? 0;
+    let qy = SELECT.from(resAnno.target).limit(limitTop, limitSkip);
+    if ((propKeys?.length ?? 0) === 0)
+        return qy;
+    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}`);
+        qy = qy.orderBy(...orderFragments);
+    }
+    if ((typeof args.q === "string" && args.q.length > 0) || args.where?.length) {
+        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 ")));
+        }
+        for (const c of args.where || []) {
+            const { field, op, value } = c;
+            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})`));
+                continue;
+            }
+            const lit = typeof value === "string"
+                ? `'${String(value).replace(/'/g, "''")}'`
+                : String(value);
+            const expr = ["contains", "startswith", "endswith"].includes(op)
+                ? `${op}(${field}, ${lit})`
+                : `${field} ${op} ${lit}`;
+            ands.push(CDS.parse.expr(expr));
+        }
+        if (ands.length)
+            qy = qy.where(ands);
+    }
+    return qy;
+}
+// Helper: execute query supporting return=count/aggregate
+// Supports three modes:
+// - rows (default): returns the selected rows
+// - count: returns { count: number }
+// - aggregate: returns aggregation result rows based on provided definitions
+async function executeQuery(CDS, svc, args, baseQuery) {
+    const { SELECT } = CDS.ql;
+    switch (args.return) {
+        case "count": {
+            const countQuery = SELECT.from(baseQuery.SELECT.from).columns("count(1) as count");
+            const result = await svc.run(countQuery);
+            const row = Array.isArray(result) ? result[0] : result;
+            return { count: row?.count ?? 0 };
+        }
+        case "aggregate": {
+            if (!args.aggregate?.length)
+                return [];
+            const cols = args.aggregate.map((a) => `${a.fn}(${a.field}) as ${a.fn}_${a.field}`);
+            const aggQuery = SELECT.from(baseQuery.SELECT.from).columns(...cols);
+            return svc.run(aggQuery);
+        }
+        default:
+            return svc.run(baseQuery);
+    }
+}

package/lib/mcp/factory.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMcpServer = createMcpServer;
+// @ts-ignore - MCP SDK types may not be present at compile time in all environments
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const logger_1 = require("../logger");
 const structures_1 = require("../annotations/structures");
@@ -8,6 +9,9 @@ const tools_1 = require("./tools");
 const resources_1 = require("./resources");
 const prompts_1 = require("./prompts");
 const utils_1 = require("../auth/utils");
+// Use relative import without extension for ts-jest resolver compatibility
+const entity_tools_1 = require("./entity-tools");
+const describe_model_1 = require("./describe-model");
 /**
  * Creates and configures an MCP server instance with the given configuration and annotations
  * @param config - CAP configuration object
@@ -27,6 +31,8 @@ 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);
     for (const entry of annotations.values()) {
         if (entry instanceof structures_1.McpToolAnnotation) {
             (0, tools_1.assignToolToServer)(entry, server, authEnabled);
@@ -34,6 +40,14 @@ function createMcpServer(config, annotations) {
         }
         else if (entry instanceof structures_1.McpResourceAnnotation) {
             (0, resources_1.assignResourceToServer)(entry, server, authEnabled);
+            // Optionally expose entities as tools based on global/per-entity switches
+            const globalWrap = !!config.wrap_entities_to_actions;
+            const localWrap = entry.wrap?.tools;
+            const enabled = localWrap === true || (localWrap === undefined && globalWrap);
+            if (enabled) {
+                const modes = config.wrap_entity_modes ?? ["query", "get"];
+                (0, entity_tools_1.registerEntityWrappers)(entry, server, authEnabled, modes);
+            }
             continue;
         }
         else if (entry instanceof structures_1.McpPromptAnnotation) {

package/lib/mcp/resources.js

@@ -6,9 +6,24 @@ const logger_1 = require("../logger");
 const utils_1 = require("./utils");
 const validation_1 = require("./validation");
 const utils_2 = require("../auth/utils");
-// import cds from "@sap/cds";
 /* @ts-ignore */
 const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
+async function resolveServiceInstance(serviceName) {
+    const CDS = global.cds || cds;
+    let svc = CDS.services?.[serviceName] || CDS.services?.[serviceName.toLowerCase()];
+    if (svc)
+        return svc;
+    const providers = (CDS.service && CDS.service.providers) ||
+        (CDS.services && CDS.services.providers) ||
+        [];
+    if (Array.isArray(providers)) {
+        const found = providers.find((p) => p?.definition?.name === serviceName || p?.name === serviceName);
+        if (found)
+            return found;
+    }
+    // do not connect; rely on served providers only to avoid duplicate cds contexts
+    return undefined;
+}
 /**
  * Registers a CAP entity as an MCP resource with optional OData query support
  * Creates either static or dynamic resources based on configured functionalities
@@ -34,7 +49,7 @@ function assignResourceToServer(model, server, authEnabled) {
     server.registerResource(model.name, template, // Type assertion to bypass strict type checking - necessary due to broken URI parser in the MCP SDK
     { title: model.target, description: detailedDescription }, async (uri, variables) => {
         const queryParameters = variables;
-        const service = cds.services[model.serviceName];
+        const service = await resolveServiceInstance(model.serviceName);
         if (!service) {
             logger_1.LOGGER.error(`Invalid service found for service '${model.serviceName}'`);
             throw new Error(`Invalid service found for service '${model.serviceName}'`);
@@ -56,7 +71,7 @@ function assignResourceToServer(model, server, authEnabled) {
                     case "filter":
                         // BUG: If filter value is e.g. "filter=1234" the value 1234 will go through
                         const validatedFilter = validator.validateFilter(v);
-                        const expression = cds.parse.expr(validatedFilter);
+                        const expression = (global.cds || cds).parse.expr(validatedFilter);
                         query.where(expression);
                         continue;
                     case "select":

package/lib/mcp/session-manager.js

@@ -63,18 +63,29 @@ class McpSessionManager {
      * @returns Configured StreamableHTTPServerTransport instance
      */
     createTransport(server) {
+        // Prefer JSON responses to avoid SSE client compatibility issues in dev/mock
+        const enableJson = (0, env_sanitizer_1.getSafeEnvVar)("MCP_ENABLE_JSON", "true") === "true" ||
+            (0, env_sanitizer_1.isTestEnvironment)();
         const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
             sessionIdGenerator: () => (0, crypto_1.randomUUID)(),
-            enableJsonResponse: (0, env_sanitizer_1.isTestEnvironment)(),
+            enableJsonResponse: enableJson,
             onsessioninitialized: (sid) => {
                 logger_1.LOGGER.debug("Session initialized with ID: ", sid);
+                logger_1.LOGGER.debug("Transport mode", { enableJsonResponse: enableJson });
                 this.sessions.set(sid, {
                     server: server,
                     transport: transport,
                 });
             },
         });
-        transport.onclose = () => this.onCloseSession(transport);
+        // In JSON response mode, HTTP connections are short-lived per request.
+        // Closing the underlying connection does NOT mean the MCP session is over.
+        // Avoid deleting the session on close when enableJson is true.
+        transport.onclose = () => {
+            if (!enableJson) {
+                this.onCloseSession(transport);
+            }
+        };
         return transport;
     }
     /**