@gavdi/cap-mcp 0.9.0

package/lib/mcp/resources.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assignResourceToServer = assignResourceToServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const logger_1 = require("../logger");
+const utils_1 = require("./utils");
+// import cds from "@sap/cds";
+/* @ts-ignore */
+const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
+function assignResourceToServer(model, server) {
+    logger_1.LOGGER.debug("Adding resource", model);
+    if (model.functionalities.size <= 0) {
+        registerStaticResource(model, server);
+    }
+    // Dynamic resource registration
+    const detailedDescription = (0, utils_1.writeODataDescriptionForResource)(model);
+    const functionalities = Array.from(model.functionalities).map((el) => `{?${el}}`);
+    // BUG: RFC compliance breaking bug in the MCP SDK library, must wait for fix....
+    const resourceTemplateUri = `odata://${model.serviceName}/${model.name}${functionalities.join("")}`;
+    const template = new mcp_js_1.ResourceTemplate(resourceTemplateUri, {
+        list: undefined,
+    });
+    server.registerResource(model.name, template, { title: model.target, description: detailedDescription }, async (uri, queryParameters) => {
+        const service = cds.services[model.serviceName];
+        const query = SELECT.from(model.target).limit(queryParameters.top ? Number(queryParameters.top) : 100, queryParameters.skip ? Number(queryParameters.skip) : undefined);
+        for (const [k, v] of Object.entries(queryParameters)) {
+            switch (k) {
+                case "filter":
+                    const expression = cds.parse.expr(decodeURIComponent(v));
+                    query.where(expression);
+                    continue;
+                case "select":
+                    const decodedSelect = decodeURIComponent(v);
+                    query.columns(decodedSelect.split(","));
+                    continue;
+                case "orderby":
+                    query.orderBy(decodeURIComponent(v));
+                    continue;
+                default:
+                    continue;
+            }
+        }
+        try {
+            const response = await service.run(query);
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: response ? JSON.stringify(response) : "",
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            logger_1.LOGGER.error(`Failed to retrieve resource data for ${model.target}`, e);
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: "ERROR: Failed to find data due to unexpected error",
+                    },
+                ],
+            };
+        }
+    });
+}
+function registerStaticResource(model, server) {
+    server.registerResource(model.name, `odata://${model.serviceName}/${model.name}`, { title: model.target, description: model.description }, async (uri, queryParameters) => {
+        const service = cds.services[model.serviceName];
+        const query = SELECT.from(model.target).limit(queryParameters.top ? Number(queryParameters.top) : 100);
+        try {
+            const response = await service.run(query);
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: response ? JSON.stringify(response) : "",
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            logger_1.LOGGER.error(`Failed to retrieve resource data for ${model.target}`, e);
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: "ERROR: Failed to find data due to unexpected error",
+                    },
+                ],
+            };
+        }
+    });
+}

package/lib/mcp/tools.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assignToolToServer = assignToolToServer;
+const utils_1 = require("./utils");
+const logger_1 = require("../logger");
+const constants_1 = require("./constants");
+/* @ts-ignore */
+const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
+/**
+ * Assigns the annotated tool to the server.
+ * This is done by reference, and will therefore mutate the provided server.
+ */
+function assignToolToServer(model, server) {
+    logger_1.LOGGER.debug("Adding tool", model);
+    const parameters = buildToolParameters(model.parameters);
+    if (model.entityKey) {
+        // Assign tool as bound operation
+        assignBoundOperation(parameters, model, server);
+        return;
+    }
+    assignUnboundOperation(parameters, model, server);
+}
+/**
+ * Creates tool handler for bound action/function imports
+ */
+function assignBoundOperation(params, model, server) {
+    if (!model.keyTypeMap || model.keyTypeMap.size <= 0) {
+        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);
+    server.registerTool(model.name, { ...keys, ...params }, async (data) => {
+        const service = cds.services[model.serviceName];
+        if (!service) {
+            logger_1.LOGGER.error("Invalid CAP service - undefined");
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: constants_1.ERR_MISSING_SERVICE,
+                    },
+                ],
+            };
+        }
+        const operationInput = {};
+        const operationKeys = {};
+        for (const [k, v] of Object.entries(data)) {
+            if (model.keyTypeMap?.has(k)) {
+                operationKeys[k] = v;
+            }
+            if (!model.parameters?.has(k))
+                continue;
+            operationInput[k] = v;
+        }
+        const response = await service.send({
+            event: model.target,
+            entity: model.entityKey,
+            data: operationInput,
+            params: [operationKeys],
+        });
+        return {
+            content: Array.isArray(response)
+                ? response.map((el) => ({ type: "text", text: String(el) }))
+                : [{ type: "text", text: String(response) }],
+        };
+    });
+}
+/**
+ * Creates a tool handler for unbound action/function imports
+ */
+function assignUnboundOperation(params, model, server) {
+    server.registerTool(model.name, params, async (data) => {
+        const service = cds.services[model.serviceName];
+        if (!service) {
+            logger_1.LOGGER.error("Invalid CAP service - undefined");
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: constants_1.ERR_MISSING_SERVICE,
+                    },
+                ],
+            };
+        }
+        const response = await service.send(model.target, data);
+        return {
+            content: Array.isArray(response)
+                ? response.map((el) => ({ type: "text", text: String(el) }))
+                : [{ type: "text", text: String(response) }],
+        };
+    });
+}
+/**
+ * Builds the parameters that the MCP server should take in for the given tool's parameters
+ */
+function buildToolParameters(params) {
+    if (!params || params.size <= 0)
+        return {};
+    const result = {};
+    for (const [k, v] of params.entries()) {
+        result[k] = (0, utils_1.determineMcpParameterType)(v);
+    }
+    return result;
+}

package/lib/mcp/types.js

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

package/lib/mcp/utils.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.determineMcpParameterType = determineMcpParameterType;
+exports.handleMcpSessionRequest = handleMcpSessionRequest;
+exports.writeODataDescriptionForResource = writeODataDescriptionForResource;
+const constants_1 = require("./constants");
+const zod_1 = require("zod");
+/**
+ * Takes in the string based type name of the CDS type found through CSN and converts it to zod type
+ */
+function determineMcpParameterType(cdsType) {
+    switch (cdsType) {
+        case "String":
+            return zod_1.z.string();
+        case "Integer":
+            return zod_1.z.number();
+        default:
+            return zod_1.z.string();
+    }
+}
+/**
+ * Session handler for MCP server.
+ * Rejects or approves incoming requests based on existing MCP session header ID
+ */
+async function handleMcpSessionRequest(req, res, sessions) {
+    const sessionIdHeader = req.headers[constants_1.MCP_SESSION_HEADER];
+    if (!sessionIdHeader || !sessions.has(sessionIdHeader)) {
+        res.status(400).send("Invalid or missing session ID");
+        return;
+    }
+    const session = sessions.get(sessionIdHeader);
+    if (!session) {
+        res.status(400).send("Invalid session");
+        return;
+    }
+    await session.transport.handleRequest(req, res);
+}
+function writeODataDescriptionForResource(model) {
+    let description = `${model.description}.${constants_1.NEW_LINE}`;
+    description += `Should be queried using OData v4 query style using the following allowed parameters.${constants_1.NEW_LINE}`;
+    description += `Parameters: ${constants_1.NEW_LINE}`;
+    if (model.functionalities.has("filter")) {
+        description += `- filter: OData $filter syntax (e.g., "$filter=author_name eq 'Stephen King'")${constants_1.NEW_LINE}`;
+    }
+    if (model.functionalities.has("top")) {
+        description += `- top: OData $top syntax (e.g., $top=10)${constants_1.NEW_LINE}`;
+    }
+    if (model.functionalities.has("skip")) {
+        description += `- skip: OData $skip syntax (e.g., $skip=10)${constants_1.NEW_LINE}`;
+    }
+    if (model.functionalities.has("select")) {
+        description += `- select: OData $select syntax (e.g., $select=property1,property2, etc..)${constants_1.NEW_LINE}`;
+    }
+    if (model.functionalities.has("orderby")) {
+        description += `- orderby: OData $orderby syntax (e.g., "$orderby=property1 asc", or "$orderby=property1 desc")${constants_1.NEW_LINE}`;
+    }
+    description += `${constants_1.NEW_LINE}Available properties on ${model.target}: ${constants_1.NEW_LINE}`;
+    for (const [key, type] of model.properties.entries()) {
+        description += `- ${key} -> value type = ${type} ${constants_1.NEW_LINE}`;
+    }
+    return description;
+}

package/lib/mcp.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const logger_1 = require("./logger");
+const crypto_1 = require("crypto");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const express_1 = __importDefault(require("express"));
+const parser_1 = require("./annotations/parser");
+const utils_1 = require("./mcp/utils");
+const factory_1 = require("./mcp/factory");
+const constants_1 = require("./mcp/constants");
+const loader_1 = require("./config/loader");
+/* @ts-ignore */
+const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
+// TODO: Handle auth
+class McpPlugin {
+    sessions;
+    config;
+    expressApp;
+    annotations;
+    constructor() {
+        logger_1.LOGGER.debug("Plugin instance created");
+        this.sessions = new Map();
+        this.config = (0, loader_1.loadConfiguration)();
+    }
+    async onBootstrap(app) {
+        logger_1.LOGGER.debug("Event received for 'bootstrap'");
+        this.expressApp = app;
+        this.expressApp.use(express_1.default.json());
+        logger_1.LOGGER.debug("WHAT IS AUTH?", cds.env.requires.auth);
+        logger_1.LOGGER.debug("WHAT IS THIS?!", cds.middlewares.auth);
+        await this.registerApiEndpoints();
+        logger_1.LOGGER.debug("Bootstrap complete");
+    }
+    async onLoaded(model) {
+        logger_1.LOGGER.debug("Event received for 'loaded'");
+        this.annotations = (0, parser_1.parseDefinitions)(model);
+        logger_1.LOGGER.debug("Annotations have been loaded");
+    }
+    async onShutdown() {
+        logger_1.LOGGER.debug("Gracefully shutting down MCP server");
+        for (const session of this.sessions.values()) {
+            await session.server.close();
+        }
+        logger_1.LOGGER.debug("MCP server sessions has been shutdown");
+    }
+    async registerApiEndpoints() {
+        logger_1.LOGGER.debug("Registering health endpoint for MCP");
+        this.expressApp?.get("/mcp/health", (_, res) => {
+            res.json({
+                status: "UP",
+            });
+        });
+        logger_1.LOGGER.debug("Registering MCP entry point");
+        this.expressApp?.post("/mcp", async (req, res) => {
+            const sessionIdHeader = req.headers[constants_1.MCP_SESSION_HEADER];
+            let sessionEntry = undefined;
+            if (sessionIdHeader && this.sessions.has(sessionIdHeader)) {
+                logger_1.LOGGER.debug("Request received - Session ID", sessionIdHeader);
+                sessionEntry = this.sessions.get(sessionIdHeader);
+            }
+            else if (!sessionIdHeader && (0, types_js_1.isInitializeRequest)(req.body)) {
+                logger_1.LOGGER.debug("Initialize session request received");
+                const server = (0, factory_1.createMcpServer)(this.config, this.annotations);
+                const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => (0, crypto_1.randomUUID)(),
+                    onsessioninitialized: (sid) => {
+                        this.sessions.set(sid, {
+                            server: server,
+                            transport: transport,
+                        });
+                    },
+                });
+                transport.onclose = () => {
+                    if (!transport.sessionId || !this.sessions.has(transport.sessionId))
+                        return;
+                    this.sessions.delete(transport.sessionId);
+                };
+                await server.connect(transport);
+                sessionEntry = {
+                    server: server,
+                    transport: transport,
+                };
+            }
+            else {
+                res.status(400).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32000,
+                        message: "Bad Request: No valid sessions ID provided",
+                        id: null,
+                    },
+                });
+            }
+            await sessionEntry?.transport.handleRequest(req, res, req.body);
+        });
+        this.expressApp?.get("/mcp", (req, res) => (0, utils_1.handleMcpSessionRequest)(req, res, this.sessions));
+        this.expressApp?.delete("/mcp", (req, res) => (0, utils_1.handleMcpSessionRequest)(req, res, this.sessions));
+    }
+}
+exports.default = McpPlugin;

package/lib/types.js

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

package/lib/utils.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_SESSION_HEADER = exports.LOGGER = void 0;
+exports.createMcpServer = createMcpServer;
+exports.handleMcpSessionRequest = handleMcpSessionRequest;
+exports.parseEntityElements = parseEntityElements;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const structures_1 = require("./annotations/structures");
+/* @ts-ignore */
+const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
+exports.LOGGER = cds.log("cds-mcp");
+exports.MCP_SESSION_HEADER = "mcp-session-id";
+function createMcpServer(annotations) {
+    const packageInfo = require("../package.json");
+    const server = new mcp_js_1.McpServer({
+        name: packageInfo.name,
+        version: packageInfo.version,
+        capabilities: {
+            tools: { listChanged: true },
+            resources: { listChanged: true },
+            prompts: { listChanged: true },
+        },
+    });
+    exports.LOGGER.debug("Annotations found for server = ", annotations);
+    if (!annotations)
+        return server;
+    // TODO: Handle the parsed annotations
+    // TODO: Error handling
+    // TODO: This should only be mapped once, not per each server instance. Maybe this should be pre-packaged on load?
+    for (const [_, v] of annotations.entries()) {
+        switch (v.constructor) {
+            case structures_1.McpToolAnnotation:
+                const model = v;
+                const parameters = buildParameters(model.parameters);
+                exports.LOGGER.debug("Adding tool", model);
+                if (model.entityKey) {
+                    const keys = buildParameters(model.keyTypeMap);
+                    server.tool(model.name, { ...keys, ...parameters }, async (data) => {
+                        const service = cds.services[model.serviceName];
+                        const received = data;
+                        const receivedKeys = {};
+                        const receivedParams = {};
+                        for (const [k, v] of Object.entries(received)) {
+                            if (model.keyTypeMap?.has(k)) {
+                                receivedKeys[k] = v;
+                            }
+                            if (!model.parameters?.has(k))
+                                continue;
+                            receivedParams[k] = v;
+                        }
+                        const response = await service.send({
+                            event: model.target,
+                            entity: model.entityKey,
+                            data: receivedParams,
+                            params: [receivedKeys],
+                        });
+                        return {
+                            content: Array.isArray(response)
+                                ? response.map((el) => ({ type: "text", text: String(el) }))
+                                : [{ type: "text", text: String(response) }], // TODO: This should be dynamic based on the return type
+                        };
+                    });
+                    continue;
+                }
+                server.tool(model.name, parameters, async (data) => {
+                    exports.LOGGER.debug("Tool call received, targeting service: ", model.serviceName, model.target);
+                    const service = cds.services[model.serviceName];
+                    const response = await service.send(model.target, data);
+                    exports.LOGGER.debug("MCP Tool response received and being packaged");
+                    return {
+                        content: Array.isArray(response)
+                            ? response.map((el) => ({ type: "text", text: String(el) }))
+                            : [{ type: "text", text: String(response) }], // TODO: This should be dynamic based on the return type
+                    };
+                });
+                continue;
+            case structures_1.McpResourceAnnotation:
+                exports.LOGGER.debug("This is a resource");
+                continue;
+            case structures_1.McpPromptAnnotation:
+                exports.LOGGER.debug("This is a prompt");
+                continue;
+            default:
+                exports.LOGGER.error("Invalid annotation data type");
+                throw new Error("Invalid annotation");
+        }
+    }
+    return server;
+}
+async function handleMcpSessionRequest(req, res, sessions) {
+    const sessionIdHeader = req.headers[exports.MCP_SESSION_HEADER];
+    if (!sessionIdHeader || !sessions.has(sessionIdHeader)) {
+        res.status(400).send("Invalid or missing session ID");
+        return;
+    }
+    const session = sessions.get(sessionIdHeader);
+    if (!session) {
+        res.status(400).send("Invalid session");
+        return;
+    }
+    await session.transport.handleRequest(req, res);
+}
+function parseEntityElements(entity) {
+    const elements = entity.elements;
+    if (!elements) {
+        exports.LOGGER.error("Invalid object - cannot be parsed", entity);
+        throw new Error("Failed to parse entity object");
+    }
+    const result = new Map();
+    for (const el of elements) {
+        if (!el.type)
+            continue;
+        result.set(el.name, el.type?.replace("cds.", ""));
+    }
+    return result;
+}
+function buildParameters(params) {
+    if (!params || params.size <= 0)
+        return {};
+    const result = {};
+    for (const [k, v] of params.entries()) {
+        result[k] = determineParameterType(v);
+    }
+    return result;
+}
+function determineParameterType(paramType) {
+    switch (paramType) {
+        case "String":
+            return zod_1.z.string();
+        case "Integer":
+            return zod_1.z.number();
+        default:
+            return zod_1.z.number();
+    }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@gavdi/cap-mcp",
+  "version": "0.9.0",
+  "description": "MCP Pluging for CAP",
+  "keywords": [
+    "MCP",
+    "CAP",
+    "plugin",
+    "SAP"
+  ],
+  "license": "Apache-2.0",
+  "author": "Simon Vestergaard Laursen",
+  "type": "commonjs",
+  "main": "cds-plugin.js",
+  "files": [
+    "lib/**/*",
+    "package.json",
+    "cds-plugin.js",
+    "index.cds",
+    "LICENSE.md"
+  ],
+  "repository": "github:gavdilabs/cap-mcp-plugin",
+  "scripts": {
+    "mock": "npm run start --workspace=test/demo",
+    "test": "jest",
+    "build": "tsc",
+    "inspect": "npx @modelcontextprotocol/inspector"
+  },
+  "peerDependencies": {
+    "@sap/cds": "^9",
+    "express": "^4"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "zod": "^3.25.67",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "devDependencies": {
+    "@cap-js/cds-types": "^0.11.0",
+    "@types/express": "^5.0.3",
+    "@types/node": "^24.0.3",
+    "eslint": "^9.29.0",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "lint-staged": "^16.1.2",
+    "prettier": "^3.5.3",
+    "release-it": "^19.0.3",
+    "ts-jest": "^29.4.0",
+    "typescript": "^5.8.3"
+  },
+  "lint-staged": {
+    "*.json": [
+      "prettier --check"
+    ],
+    "*.ts": [
+      "eslint",
+      "prettier --check ./src"
+    ],
+    "*.js": [
+      "eslint",
+      "prettier --check ./src"
+    ]
+  },
+  "workspaces": [
+    "test/demo"
+  ]
+}