@gavdi/cap-mcp 0.9.3 → 0.9.7

package/README.md

@@ -60,7 +60,9 @@ Add MCP configuration to your `package.json`:
   "cds": {
     "mcp": {
       "name": "my-bookshop-mcp",
-      "auth": "inherit"
+      "auth": "inherit",
+      "wrap_entities_to_actions": false,
+      "wrap_entity_modes": ["query", "get"]
     }
   }
 }
@@ -80,6 +82,13 @@ service CatalogService {
     resource: ['filter', 'orderby', 'select', 'top', 'skip']
   }
   entity Books as projection on my.Books;
+  
+  // Optionally expose Books as tools for LLMs (query/get enabled by default config)
+  annotate CatalogService.Books with @mcp.wrap: {
+    tools: true,
+    modes: ['query','get'],
+    hint: 'Use for read-only lookups of books'
+  };
 
   @mcp: {
     name: 'get-book-recommendations',
@@ -114,10 +123,32 @@ This plugin transforms your annotated CAP services into a fully functional MCP s
 
 - **📊 Resources**: Expose CAP entities as MCP resources with OData v4 query capabilities
 - **🔧 Tools**: Convert CAP functions and actions into executable MCP tools
+- **🧩 Entity Wrappers (optional)**: Expose CAP entities as tools (`query`, `get`, and optionally `create`, `update`) for LLM tool use while keeping resources intact
 - **💡 Prompts**: Define reusable prompt templates for AI interactions
 - **🔄 Auto-generation**: Automatically creates MCP server endpoints based on annotations
 - **⚙️ Flexible Configuration**: Support for custom parameter sets and descriptions
 
+## 🧪 Testing & Inspector
+
+- Run tests: `npm test`
+- Start demo app: `npm run mock`
+- Inspector: `npx @modelcontextprotocol/inspector`
+
+### New wrapper tools
+
+When `wrap_entities_to_actions` is enabled (globally or via `@mcp.wrap.tools: true`), you will see tools named like:
+
+- `CatalogService_Books_query`
+- `CatalogService_Books_get`
+- `CatalogService_Books_create` (if enabled)
+- `CatalogService_Books_update` (if enabled)
+
+Each tool includes a description with fields and OData notes to guide the model. You can add `@mcp.wrap.hint` per entity to enrich descriptions for LLMs.
+
+### Bruno collection
+
+The `bruno/` folder contains HTTP requests for the MCP endpoint (handy for local manual testing using Bruno or any HTTP client). You may add calls for `tools/list` and `tools/call` to exercise the new wrapper tools.
+
 ## 📝 Usage
 
 ### Resource Annotations
@@ -425,6 +456,10 @@ npm test -- --verbose
 npm test -- --watch
 ```
 
+### Further reading
+
+- Short guide on entity tools and configuration: `docs/entity-tools.md`
+
 ## 🤝 Contributing
 
 Contributions are welcome! This is an open-source project aimed at bridging CAP applications with the AI ecosystem.

package/cds-plugin.js

@@ -1,4 +1,4 @@
-const cds = global.cds || require("@sap/cds");
+const cds = global.cds; // enforce host app cds instance
 const McpPlugin = require("./lib/mcp").default;
 
 const plugin = new McpPlugin();

package/lib/annotations/constants.js

@@ -25,6 +25,8 @@ exports.MCP_ANNOTATION_PROPS = {
     MCP_TOOL: "@mcp.tool",
     /** Prompt templates annotation for CAP services */
     MCP_PROMPT: "@mcp.prompts",
+    /** Wrapper configuration for exposing entities as tools */
+    MCP_WRAP: "@mcp.wrap",
 };
 /**
  * Default set of all available OData query options for MCP resources

package/lib/annotations/parser.js

@@ -18,16 +18,18 @@ function parseDefinitions(model) {
     }
     const result = new Map();
     for (const [key, value] of Object.entries(model.definitions)) {
-        const parsedAnnotations = parseAnnotations(value);
+        // Narrow unknown to csn.Definition with a runtime check
+        const def = value;
+        const parsedAnnotations = parseAnnotations(def);
         const { serviceName, target } = (0, utils_1.splitDefinitionName)(key);
-        parseBoundOperations(serviceName, target, value, result); // Mutates result map with bound operations
+        parseBoundOperations(serviceName, target, def, result); // Mutates result map with bound operations
         if (!parsedAnnotations || !(0, utils_1.containsRequiredAnnotations)(parsedAnnotations)) {
             continue; // This check must occur here, since we do want the bound operations even if the parent is not annotated
         }
         const verifiedAnnotations = parsedAnnotations;
-        switch (value.kind) {
+        switch (def.kind) {
             case "entity":
-                const resourceAnnotation = constructResourceAnnotation(serviceName, target, verifiedAnnotations, value);
+                const resourceAnnotation = constructResourceAnnotation(serviceName, target, verifiedAnnotations, def);
                 if (!resourceAnnotation)
                     continue;
                 result.set(resourceAnnotation.target, resourceAnnotation);
@@ -87,6 +89,10 @@ function parseAnnotations(definition) {
             case constants_1.MCP_ANNOTATION_PROPS.MCP_PROMPT:
                 annotations.prompts = v;
                 continue;
+            case constants_1.MCP_ANNOTATION_PROPS.MCP_WRAP:
+                // Wrapper container to expose resources as tools
+                annotations.wrap = v;
+                continue;
             default:
                 continue;
         }
@@ -106,7 +112,7 @@ function constructResourceAnnotation(serviceName, target, annotations, definitio
         return undefined;
     const functionalities = (0, utils_1.determineResourceOptions)(annotations);
     const { properties, resourceKeys } = (0, utils_1.parseResourceElements)(definition);
-    return new structures_1.McpResourceAnnotation(annotations.name, annotations.description, target, serviceName, functionalities, properties, resourceKeys);
+    return new structures_1.McpResourceAnnotation(annotations.name, annotations.description, target, serviceName, functionalities, properties, resourceKeys, annotations.wrap);
 }
 /**
  * Constructs a tool annotation from parsed annotation data

package/lib/annotations/structures.js

@@ -68,6 +68,8 @@ class McpResourceAnnotation extends McpAnnotation {
     _properties;
     /** Map of resource key fields to their types */
     _resourceKeys;
+    /** Optional wrapper configuration to expose this resource as tools */
+    _wrap;
     /**
      * Creates a new MCP resource annotation
      * @param name - Unique identifier for this resource
@@ -78,11 +80,12 @@ class McpResourceAnnotation extends McpAnnotation {
      * @param properties - Map of entity properties to their CDS types
      * @param resourceKeys - Map of key fields to their types
      */
-    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys) {
+    constructor(name, description, target, serviceName, functionalities, properties, resourceKeys, wrap) {
         super(name, description, target, serviceName);
         this._functionalities = functionalities;
         this._properties = properties;
         this._resourceKeys = resourceKeys;
+        this._wrap = wrap;
     }
     /**
      * Gets the set of enabled OData query functionalities
@@ -105,6 +108,12 @@ class McpResourceAnnotation extends McpAnnotation {
     get resourceKeys() {
         return this._resourceKeys;
     }
+    /**
+     * Gets the wrapper configuration for exposing this resource as tools
+     */
+    get wrap() {
+        return this._wrap;
+    }
 }
 exports.McpResourceAnnotation = McpResourceAnnotation;
 /**

package/lib/auth/utils.js

@@ -4,6 +4,8 @@ exports.isAuthEnabled = isAuthEnabled;
 exports.getAccessRights = getAccessRights;
 exports.registerAuthMiddleware = registerAuthMiddleware;
 const handler_1 = require("./handler");
+const proxyProvider_js_1 = require("@modelcontextprotocol/sdk/server/auth/providers/proxyProvider.js");
+const router_js_1 = require("@modelcontextprotocol/sdk/server/auth/router.js");
 /**
  * @fileoverview Authentication utilities for MCP-CAP integration.
  *
@@ -128,4 +130,83 @@ function registerAuthMiddleware(expressApp) {
     authMiddleware.push((0, handler_1.authHandlerFactory)());
     // Apply auth middleware to all /mcp routes EXCEPT health
     expressApp?.use(/^\/mcp(?!\/health).*/, ...authMiddleware);
+    // Then finally we add the oauth proxy to the xsuaa instance
+    configureOAuthProxy(expressApp);
+}
+/**
+ * Configures OAuth proxy middleware for enterprise authentication scenarios.
+ *
+ * This function sets up a proxy OAuth provider that integrates with SAP BTP
+ * authentication services (XSUAA/IAS) to enable MCP clients to authenticate
+ * through standard OAuth2 flows. The proxy handles:
+ *
+ * - OAuth2 authorization and token endpoints
+ * - Access token verification and validation
+ * - Client credential management
+ * - Integration with CAP authentication configuration
+ *
+ * The OAuth proxy is only configured for enterprise authentication types
+ * (jwt, xsuaa, ias) and skips configuration for basic auth types.
+ *
+ * @param expressApp - Express application instance to register OAuth routes on
+ *
+ * @throws {Error} When required OAuth credentials are missing or invalid
+ *
+ * @example
+ * ```typescript
+ * // Automatically called by registerAuthMiddleware()
+ * // Requires CAP auth configuration:
+ * // cds.env.requires.auth = {
+ * //   kind: 'xsuaa',
+ * //   credentials: {
+ * //     clientid: 'your-client-id',
+ * //     clientsecret: 'your-client-secret',
+ * //     url: 'https://your-tenant.authentication.sap.hana.ondemand.com'
+ * //   }
+ * // }
+ * ```
+ *
+ * @internal This function is called internally by registerAuthMiddleware()
+ * @since 1.0.0
+ */
+function configureOAuthProxy(expressApp) {
+    const config = cds.env.requires.auth;
+    const kind = config.kind;
+    const credentials = config.credentials;
+    // Safety guard - skip OAuth proxy for basic auth types
+    if (kind === "dummy" || kind === "mocked" || kind === "basic")
+        return;
+    else if (!credentials ||
+        !credentials.clientid ||
+        !credentials.clientsecret ||
+        !credentials.url) {
+        throw new Error("Invalid security credentials");
+    }
+    const proxyProvider = new proxyProvider_js_1.ProxyOAuthServerProvider({
+        endpoints: {
+            authorizationUrl: `${credentials.url}/oauth/authorize`,
+            tokenUrl: `${credentials.url}/oauth/token`,
+            revocationUrl: `${credentials.url}/oauth/revoke`,
+        },
+        verifyAccessToken: async (token) => {
+            return {
+                token,
+                clientId: credentials.clientid,
+                scopes: ["uaa.resource"],
+            };
+        },
+        getClient: async (client_id) => {
+            return {
+                client_secret: credentials.clientsecret,
+                client_id,
+                redirect_uris: ["http://localhost:3000/callback"], // Temporary value for now
+            };
+        },
+    });
+    expressApp.use((0, router_js_1.mcpAuthRouter)({
+        provider: proxyProvider,
+        issuerUrl: new URL(credentials.url),
+        //baseUrl: new URL(""), // I have left this out for the time being due to the defaulting to issuer
+        serviceDocumentationUrl: new URL("https://docs.cloudfoundry.org/api/uaa/version/77.34.0/index.html#authorization"),
+    }));
 }

package/lib/config/loader.js

@@ -28,6 +28,13 @@ function loadConfiguration() {
             resources: cdsEnv?.capabilities?.resources ?? { listChanged: true },
             prompts: cdsEnv?.capabilities?.prompts ?? { listChanged: true },
         },
+        wrap_entities_to_actions: cdsEnv?.wrap_entities_to_actions ?? false,
+        wrap_entity_modes: cdsEnv?.wrap_entity_modes ?? [
+            "query",
+            "get",
+            "create",
+            "update",
+        ],
     };
 }
 /**

package/lib/logger.js

@@ -7,8 +7,54 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LOGGER = void 0;
 /* @ts-ignore */
 const cds = global.cds || require("@sap/cds"); // This is a work around for missing cds context
+// In some test/mocked environments cds.log may not exist. Provide a no-op fallback.
+const safeLog = (ns) => {
+    try {
+        if (typeof cds?.log === "function")
+            return cds.log(ns);
+    }
+    catch { }
+    return {
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+    };
+};
+// Create both channels so logs show up even if the app configured "mcp" instead of "cds-mcp"
+const loggerPrimary = safeLog("cds-mcp");
+const loggerCompat = safeLog("mcp");
 /**
  * Shared logger instance for all MCP plugin components
- * Provides debug, info, warn, and error logging methods
+ * Multiplexes logs to both "cds-mcp" and legacy "mcp" channels for visibility
  */
-exports.LOGGER = cds.log("cds-mcp");
+exports.LOGGER = {
+    debug: (...args) => {
+        try {
+            loggerPrimary?.debug?.(...args);
+            loggerCompat?.debug?.(...args);
+        }
+        catch { }
+    },
+    info: (...args) => {
+        try {
+            loggerPrimary?.info?.(...args);
+            loggerCompat?.info?.(...args);
+        }
+        catch { }
+    },
+    warn: (...args) => {
+        try {
+            loggerPrimary?.warn?.(...args);
+            loggerCompat?.warn?.(...args);
+        }
+        catch { }
+    },
+    error: (...args) => {
+        try {
+            loggerPrimary?.error?.(...args);
+            loggerCompat?.error?.(...args);
+        }
+        catch { }
+    },
+};

package/lib/mcp/describe-model.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDescribeModelTool = registerDescribeModelTool;
+const utils_1 = require("./utils");
+const zod_1 = require("zod");
+/**
+ * Registers a discovery tool that describes CAP services/entities and fields.
+ * Helpful for models to plan correct tool calls without trial-and-error.
+ */
+function registerDescribeModelTool(server) {
+    const inputZod = zod_1.z
+        .object({
+        service: zod_1.z.string().optional(),
+        entity: zod_1.z.string().optional(),
+        format: zod_1.z.enum(["concise", "detailed"]).default("concise").optional(),
+    })
+        .strict();
+    const inputSchema = {
+        service: inputZod.shape.service,
+        entity: inputZod.shape.entity,
+        format: inputZod.shape.format,
+    };
+    server.registerTool("cap_describe_model", {
+        title: "cap_describe_model",
+        description: "Describe CAP services/entities and their fields, keys, and example tool calls. Use this to guide LLMs how to call entity wrapper tools.",
+        inputSchema,
+    }, async (rawArgs) => {
+        const args = inputZod.parse(rawArgs);
+        const CDS = global.cds;
+        const refl = CDS.reflect(CDS.model);
+        const listServices = () => {
+            const names = Object.values(CDS.services || {})
+                .map((s) => s?.definition?.name || s?.name)
+                .filter(Boolean);
+            return { services: [...new Set(names)].sort() };
+        };
+        const listEntities = (service) => {
+            const all = Object.values(refl.entities || {}) || [];
+            const filtered = service
+                ? all.filter((e) => String(e.name).startsWith(service + "."))
+                : all;
+            return {
+                entities: filtered.map((e) => e.name).sort(),
+            };
+        };
+        const describeEntity = (service, entity) => {
+            if (!entity)
+                return { error: "Please provide 'entity'." };
+            const fqn = service && !entity.includes(".") ? `${service}.${entity}` : entity;
+            const ent = (refl.entities || {})[fqn] || (refl.entities || {})[entity];
+            if (!ent)
+                return {
+                    error: `Entity not found: ${entity}${service ? ` (service ${service})` : ""}`,
+                };
+            const elements = Object.entries(ent.elements || {}).map(([name, el]) => ({
+                name,
+                type: el.type,
+                key: !!el.key,
+                target: el.target || undefined,
+                isArray: !!el.items,
+            }));
+            const keys = elements.filter((e) => e.key).map((e) => e.name);
+            const sampleTop = 5;
+            const shortFields = elements.slice(0, 5).map((e) => e.name);
+            // Match wrapper tool naming: Service_Entity_mode
+            const entName = String(ent?.name || "entity");
+            const svcPart = service || entName.split(".")[0] || "Service";
+            const entityBase = entName.split(".").pop() || "Entity";
+            const listName = `${svcPart}_${entityBase}_query`;
+            const getName = `${svcPart}_${entityBase}_get`;
+            return {
+                service,
+                entity: ent.name,
+                keys,
+                fields: elements,
+                usage: {
+                    rationale: "Entity wrapper tools expose CRUD-like operations for LLMs. Prefer query/get globally; create/update must be explicitly enabled by the developer.",
+                    guidance: "Use the *_query tool for retrieval with filters and projections; use *_get with keys for a single record; use *_create/*_update only if enabled and necessary.",
+                },
+                examples: {
+                    list_tool: listName,
+                    list_tool_payload: {
+                        top: sampleTop,
+                        select: shortFields,
+                    },
+                    get_tool: getName,
+                    get_tool_payload: keys.length ? { [keys[0]]: "<value>" } : {},
+                },
+            };
+        };
+        let json;
+        if (!args.service && !args.entity) {
+            json = { ...listServices(), ...listEntities(undefined) };
+        }
+        else if (args.service && !args.entity) {
+            json = { service: args.service, ...listEntities(args.service) };
+        }
+        else {
+            json = describeEntity(args.service, args.entity);
+        }
+        return (0, utils_1.asMcpResult)(json);
+    });
+}