From a50346bbe166f6b96c060933df418fe299332ee8 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Mon, 24 Aug 2026 09:49:13 +0200 Subject: [PATCH 1/4] Remove outdated limitation --- java/developing-applications/building.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/java/developing-applications/building.md b/java/developing-applications/building.md index 94d553d9f7..9898c44a24 100644 --- a/java/developing-applications/building.md +++ b/java/developing-applications/building.md @@ -554,10 +554,6 @@ Other options in this goal enable or disable certain features that change the wa If your entity is modelled with the [composition of aspects](../../cds/cdl#with-named-targets), the generated interfaces always reference original aspect as type for setters and getters. When this switch is enabled, the code generator uses the type generated by the compiler instead of the type of the aspect itself and will include methods to fetch keys, for example. - :::warning Limitations - This is supported only for the named aspects (inline targets are not supported) and does not respect all possible options how such entities might be exposed by services. - ::: - - [`betterNames`](../assets/cds-maven-plugin-site/generate-mojo.html#betterNames) CDS models from external sources might include elements that have some special characters in their names or include elements that clash with Java keywords. Such cases always can be solved with the [renaming features](../cds-data#renaming-elements-in-java) provided by code generator, but in case of large models, this is tedious. From 91b02a06f397e606f0f241b5a1f9982945599984 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Wed, 26 Aug 2026 17:24:25 +0200 Subject: [PATCH 2/4] First updates --- guides/protocols/mcp.md | 43 +++++++++++++++++------------------------ 1 file changed, 18 insertions(+), 25 deletions(-) diff --git a/guides/protocols/mcp.md b/guides/protocols/mcp.md index 47ec059c94..4b9f8691ca 100644 --- a/guides/protocols/mcp.md +++ b/guides/protocols/mcp.md @@ -75,17 +75,13 @@ Add this to the *srv/pom.xml* file: com.sap.cds cds-adapter-mcp + runtime ${cds.services.version} ``` ::: -> [!note] Not yet public -> The feature is not yet released publicly. Stay tuned. -> -> Make sure internal artifactory is configured for Maven build as described in [*Java > Getting Started > Setting Up Local Development*](../../java/getting-started.md#local). - ## Serving MCP ### Annotate services with `@mcp` @@ -112,7 +108,7 @@ Start your server with `cds watch` or `mvn cds:watch` and note that the MCP serv } ``` ```shell [Java] -INFO com.sap.cds.adapter.mcp.McpServlet : MCP Server initialized at endpoint '/mcp/browse' for service 'CatalogService' +c.s.c.f.s.c.adapter.AdapterBeanFactory : Servlet McpServlet mapped to /mcp ``` ::: @@ -156,12 +152,13 @@ using { AdminService } from './admin-service'; As LLMs rely heavily on context information to create high-quality output, the adapter evaluates existing doc comments and annotations to provide additional information about the service, entities, elements, actions, and parameters to the LLM. This information is included in the output of the [`describe`](#tool-describe) tool and can be used by agents to better understand the data model and available actions/functions. In particular, the following information is evaluated: -- [Doc comments](../../cds/cdl#doc-comments) -> most recommended (Node.js only) +- [Doc comments](../../cds/cdl#doc-comments) - `@title` - `@description` > [!note] -> Doc comments are only supported in Node.js. In Java, use `@title` and `@description` annotations instead. +> For CAP Java, you need to enable this using configuration parameter cds.model.includeDocComments: true and in MTX sidecar + For example, you can add doc comments to your entities and their elements like that: @@ -243,9 +240,8 @@ claude "list books with authors and genres" ``` ::: code-group ```zsh [=> Output] -⏺ cds:AdminService - query (MCP)(entity: "Books", select: ["ID","title","author.name","genre.name","stock","price"], limit: 20) +⏺ cds:CatalogService - query (MCP)(cql: "SELECT ID, title, author, genre FROM Books ORDER BY title") ⎿  { - "entity": "Books", "count": 5, … +43 lines (ctrl+o to expand) @@ -279,7 +275,7 @@ opencode run list books with authors and genres ``` ::: code-group ```zsh [=> Output] -⚙ cds_AdminService_query {"entity":"Books","select":["ID","title","stock","price","author.name","genre.name"],"limit":20} +⚙ cds_CatalogService_query [cql=SELECT ID, title, author, genre, stock, price, currency_code FROM Books] Here are the books with their authors and genres: @@ -309,20 +305,12 @@ For example, for the above query, you should see log output similar to this: ::: code-group ```js [Node.js] [mcp] - query { - service: 'AdminService', - entity: 'Books', - select: [ - { ref: [ 'ID' ] }, - { ref: [ 'title' ] }, - { ref: [ 'stock' ] }, - { ref: [ 'price' ] }, - { ref: [ 'author', 'name' ] }, - { ref: [ 'genre', 'name' ] } - ] + service: 'CatalogService', + cql: 'SELECT ID, title, author, genre FROM Books ORDER BY title' } ``` ```js [Java] -INFO com.sap.cds.adapter.mcp.McpServlet : Received MCP query request for entity 'Books' with select fields [ID, title, author.name, genre.name, stock, price] and limit 20 +MCP tool called: service='CatalogService', tool='query', arguments={cql=SELECT from Books { ID, title, author { ID, name }, genre { ID, name } }} ``` ::: @@ -437,10 +425,15 @@ The adapter creates an MCP server per CAP service, hence each CAP application ca > They may change in the future based on the needs of LLMs and AI agents. For stable APIs, please use the existing CAP protocols like OData, REST, GraphQL, etc. #### Tool: `describe` -This tool returns information about the entities and their elements exposed by the service. It also returns information about unbound actions and functions. If you do not provide a parameter, the tool describes all exposed entities, actions and functions. The optional parameter `entity` restricts the output to a single entity, the optional parameter `action` restricts the output to a single action/function. The tool provides an enum that lists all available entities, actions and functions. +This tool returns information about the entities and their elements exposed by the service. It also returns information about unbound actions and functions. If you do not provide a parameter, the tool describes all exposed entities, actions and functions. The optional parameter `entities` restricts the output to a single entity, the optional parameter `actions` restricts the output to a single action/function. The tool provides an enum that lists all available entities, actions and functions. #### Tool: `query` -This tool is used to read data from the service. The only required parameter is `entity`, an enum that lists all entities exposed by the service. This tool takes all provided parameters and translates them to a [CQN](../../cds/cqn) query, which the service runs via `service.run(query)`. The parameter descriptions explain how to use them. + +This tool is used to read data from the service. It accepts single parameter `cql` with the CQL statement to execute. + +There is also an additional mode for this tool, where it accepts CQN statement. This is controlled by the tool configuration. + +In this mode, the only required parameter is `entity`, an enum that lists all entities exposed by the service. This tool takes all provided parameters and translates them to a [CQN](../../cds/cqn) query, which the service runs via `service.run(query)`. The parameter descriptions explain how to use them. Parameters of `query` requests: @@ -456,7 +449,7 @@ Parameters of `query` requests: | orderBy | List of objects to order the results (ref, sort, nulls) | -#### Tool: `call_action` +#### Tool: `call` This tool is used to call unbound actions or functions. The required parameter `action` is an enum that lists all unbound actions and functions exposed by the service. The parameters of the action or function to call can be provided via the optional parameter `parameters`, that must contain all required parameters of the action or function. The tool takes these parameters and calls the action or function on the service. From 83bcf09a04c25c815620938ab5ec6a64c0e5aa97 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Thu, 27 Aug 2026 12:09:39 +0200 Subject: [PATCH 3/4] Add more stuff --- guides/protocols/mcp.md | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/guides/protocols/mcp.md b/guides/protocols/mcp.md index 4b9f8691ca..7cc6ee285a 100644 --- a/guides/protocols/mcp.md +++ b/guides/protocols/mcp.md @@ -76,7 +76,6 @@ Add this to the *srv/pom.xml* file: com.sap.cds cds-adapter-mcp runtime - ${cds.services.version} ``` @@ -152,14 +151,10 @@ using { AdminService } from './admin-service'; As LLMs rely heavily on context information to create high-quality output, the adapter evaluates existing doc comments and annotations to provide additional information about the service, entities, elements, actions, and parameters to the LLM. This information is included in the output of the [`describe`](#tool-describe) tool and can be used by agents to better understand the data model and available actions/functions. In particular, the following information is evaluated: -- [Doc comments](../../cds/cdl#doc-comments) +- [Doc comments](../../cds/cdl#doc-comments) - most recommended - `@title` - `@description` -> [!note] -> For CAP Java, you need to enable this using configuration parameter cds.model.includeDocComments: true and in MTX sidecar - - For example, you can add doc comments to your entities and their elements like that: ```cds @@ -178,6 +173,34 @@ entity Authors { ``` +> [!warning] Configuration required +For CAP Java, you must enable doc comments in the Java application and in the MTX sidecar. +::: code-group +```json [.cdsrc.json] +"cdsc": { + "docs": true +} +``` +```yaml [srv/application.yaml] +cds: + model.includeDocComments: true +``` +::: + +You can also provide service-specific instructions via annotation `@mcp.instructions`. + +::: code-group +```cds [srv/books-service.cds] +using { AdminService } from './admin-service'; +@mcp +@mcp.instructions: 'Always ask a confirmation before ordering any books' // [!code focus] +service BooksService { + ... +} +``` +::: + +These instructions are sent to a client who connects with an MCP server. ## Test-drive Locally From c570e9cffa5bd47cc441c7b479e289859faad91a Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 28 Aug 2026 14:12:12 +0200 Subject: [PATCH 4/4] fix warning syntax --- guides/protocols/mcp.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/guides/protocols/mcp.md b/guides/protocols/mcp.md index 7cc6ee285a..a869304895 100644 --- a/guides/protocols/mcp.md +++ b/guides/protocols/mcp.md @@ -173,8 +173,9 @@ entity Authors { ``` -> [!warning] Configuration required -For CAP Java, you must enable doc comments in the Java application and in the MTX sidecar. +::: warning Configuration required for CAP Java +You must enable doc comments in the Java application and in the MTX sidecar. + ::: code-group ```json [.cdsrc.json] "cdsc": {