@gavdi/cap-mcp 0.9.8 → 0.9.9

package/README.md

@@ -3,7 +3,7 @@
 > This implementation is based on the Model Context Protocol (MCP) put forward by Anthropic.
 > For more information on MCP, please have a look at their [official documentation.](https://modelcontextprotocol.io/introduction)
 
-> 🔧 **In active development - 1.0 release scheduled for Summer 2025**
+> 🔧 **In active development - 1.0 release scheduled for September 2025**
 
 # CAP-MCP Plugin
 
@@ -15,7 +15,7 @@ Transform your CAP OData services into AI-accessible resources, tools, and promp
 The Model Context Protocol bridges the gap between your enterprise data and AI agents.
 By integrating MCP with your CAP applications, you unlock:
 
-- **AI-Native Data Access**: Your CAP services become directly accessible to AI agents like Claude, enabling natural language queries against your business data
+- **AI-Native Data Access**: Your CAP services become directly accessible to MCP enabled AI agents like Claude, enabling natural language queries against your business data
 - **Enterprise Integration**: Seamlessly connect AI tools to your SAP systems, databases, and business logic
 - **Intelligent Automation**: Enable AI agents to perform complex business operations by combining multiple CAP service calls
 - **Developer Productivity**: Allow AI assistants to help developers understand, query, and work with your CAP data models
@@ -23,19 +23,11 @@ By integrating MCP with your CAP applications, you unlock:
 
 ## ⚠️ Development Status
 
-**This plugin is currently in active development (v0.9.2) and approaching production readiness.**
+**This plugin is currently in active development and approaching production readiness.**
 APIs and annotations may change in future releases. Authentication and security features are implemented and tested.
 
 Version 1.0 of the plugin is scheduled for release in Summer 2025 after final stability testing and documentation completion.
 
-## 📦 Installation
-
-```bash
-npm install @gavdi/cap-mcp
-```
-
-The plugin follows CAP's standard plugin architecture and will automatically integrate with your CAP application.
-
 ## 🚀 Quick Setup
 
 ### Prerequisites
@@ -51,6 +43,8 @@ The plugin follows CAP's standard plugin architecture and will automatically int
 npm install @gavdi/cap-mcp
 ```
 
+The plugin follows CAP's standard plugin architecture and will automatically integrate with your CAP application upon installation.
+
 ### Step 2: Configure Your CAP Application
 
 Add MCP configuration to your `package.json`:
@@ -83,7 +77,7 @@ 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,
@@ -135,17 +129,6 @@ This plugin transforms your annotated CAP services into a fully functional MCP s
 - 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.
@@ -197,6 +180,33 @@ service CatalogService {
 - **Dynamic Filtering**: Complex filter expressions using OData syntax
 - **Flexible Selection**: Choose specific fields and sort orders
 
+### 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.
+
+Example:
+
+```cds
+  // Wrap Books entity as tools for query/get/create/update (demo)
+  annotate CatalogService.Books with @mcp.wrap: {
+    tools: true,
+    modes: [
+      'query',
+      'get',
+      'create',
+      'update'
+    ],
+    hint : 'Use for read and write demo operations'
+  };
+```
+
 ### Tool Annotations
 
 Convert CAP functions and actions into executable AI tools:
@@ -277,6 +287,7 @@ Configure the MCP plugin through your CAP application's `package.json` or `.cdsr
 | `name` | string | package.json name | MCP server name |
 | `version` | string | package.json version | MCP server version |
 | `auth` | `"inherit"` \| `"none"` | `"inherit"` | Authentication mode |
+| `instructions` | string | `null` | MCP server instructions for agents |
 | `capabilities.resources.listChanged` | boolean | `true` | Enable resource list change notifications |
 | `capabilities.resources.subscribe` | boolean | `false` | Enable resource subscriptions |
 | `capabilities.tools.listChanged` | boolean | `true` | Enable tool list change notifications |
@@ -540,8 +551,6 @@ npm test -- --testPathPattern=integration
 
 ### Known Limitations
 - **SDK Bug**: Dynamic resource queries require all query parameters due to `@modelcontextprotocol/sdk` RFC template string issue
-- **Authentication Inheritance**: MCP authentication is tightly coupled to CAP's authentication system
-- **Session Cleanup**: MCP sessions are cleaned up on HTTP connection close, not on explicit disconnect
 
 ### Performance Considerations
 - **Large Datasets**: Use `resource: ['top']` or similar constraints for entities with many records

package/lib/mcp/describe-model.js

@@ -61,7 +61,11 @@ function registerDescribeModelTool(server) {
             }));
             const keys = elements.filter((e) => e.key).map((e) => e.name);
             const sampleTop = 5;
-            const shortFields = elements.slice(0, 5).map((e) => e.name);
+            // Prefer scalar fields for sample selects; exclude associations
+            const scalarFields = elements
+                .filter((e) => String(e.type).toLowerCase() !== "cds.association")
+                .map((e) => e.name);
+            const shortFields = scalarFields.slice(0, 5);
             // Match wrapper tool naming: Service_Entity_mode
             const entName = String(ent?.name || "entity");
             const svcPart = service || entName.split(".")[0] || "Service";
@@ -75,7 +79,7 @@ function registerDescribeModelTool(server) {
                 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.",
+                    guidance: "Use the *_query tool for retrieval with filters and projections. All fields in select/where are consistent. For associations, use foreign key fields (e.g., author_ID not author). Use *_get with keys for a single record; use *_create/*_update only if enabled and necessary.",
                 },
                 examples: {
                     list_tool: listName,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavdi/cap-mcp",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "MCP Pluging for CAP",
   "keywords": [
     "MCP",
@@ -41,12 +41,12 @@
     "express": "^4"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.17.1",
+    "@modelcontextprotocol/sdk": "^1.17.3",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.5"
   },
   "devDependencies": {
-    "@cap-js/cds-types": "^0.12.0",
+    "@cap-js/cds-types": "^0.13.0",
     "@release-it/conventional-changelog": "^10.0.1",
     "@types/express": "^5.0.3",
     "@types/jest": "^30.0.0",