From cdfe498e5f45f726d8805ea1870cd8901aa9b351 Mon Sep 17 00:00:00 2001 From: D051920 Date: Mon, 28 Sep 2026 15:28:31 +0200 Subject: [PATCH 1/5] fix: xtravels using MCP and agents --- guides/ai/xtravels-sample.md | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/guides/ai/xtravels-sample.md b/guides/ai/xtravels-sample.md index b3baf9926..780bbf3c6 100644 --- a/guides/ai/xtravels-sample.md +++ b/guides/ai/xtravels-sample.md @@ -101,6 +101,15 @@ This is exactly where the MCP services come into play, automating much of the pl ## MCP Services +### Install the MCP Plugin + +Before using MCP services, install the MCP plugin in the xtravels project: + +```shell +cd xtravels +npm install @cap-js/mcp --save +``` + ### MCP-enable given Services Instead of implementing static UIs, we merely annotate the existing service definitions with [`@mcp`] to make them available for automated planning and booking from AI agents: @@ -160,12 +169,21 @@ In case of the XTravels application we choose to not just [`@mcp`]-enable the ex CAP puts a main focus on [fast inner-loop development](../integration/inner-loops) and iterative testing, making it easy to quickly see the effects of changes in your services. This also holds true for MCP-enabled services, which we can test locally using local installations of [OpenCode](https://opencode.ai/), [Claude Code](https://claude.ai/), or any other MCP client. +> [!note] MCP Client Prerequisites +> MCP clients like OpenCode require an LLM API key to be configured before use. See your client's documentation for setup instructions. + +> [!note] Different AI Client Behaviors +> Different MCP clients may have different interaction patterns. The screenshots below show OpenCode's style. Your experience may vary with other clients. + With the above changes, restart your CAP server in a terminal: ```shell cds w xtravels ``` +> [!note] MCP Auto-wiring +> When `cds watch` starts, CAP automatically writes MCP server entries to your MCP client's configuration files (e.g., `~/.opencode/config.json` for OpenCode or `~/.claude.json` for Claude Code). These entries **persist after the server stops**. If you work with multiple CAP projects or change ports/services, you may need to manually clean up stale entries from these config files. + In a separate terminal, start OpenCode: ```shell @@ -221,10 +239,10 @@ The `TravelAgentService` is our root agent that coordinates travel planning and > [!tip] -> Simply checkout the `aix` branch of the `xtravels` repository to get the complete implementation of the agents: +> Simply checkout the `jv-agents` branch of the `xtravels` repository to get the complete implementation of the agents: > ```shell > cd xtravels -> git checkout aix +> git checkout jv-agents > cd - > ``` @@ -271,7 +289,7 @@ cds w xtravels See [Automatic Config](cap-agents#automatic-config) in the CAP Agents documentation for details. ::: -But instead of using OpenCode as a generic client, we use the Chat Preview provided by the `cap-js/agent` plugin, which you can open from `Preview` links that are available in the _index.html_ for A2A agent endpoints – or simply open http://localhost:4005/agent/preview. +But instead of using OpenCode as a generic client, we use the Chat Preview provided by the `cap-js/agent` plugin, which you can open from `Preview` links that are available in the _index.html_ for A2A agent endpoints – or simply open http://localhost:4004/a2a/travel-agent/preview. ![Opening chat preview from index.html](chat-preview-from-index-html.png){style="width: 500px;"} @@ -301,18 +319,21 @@ To run the XTravels application with its services separately, you can start each Run each of the lines below in a separate terminal, in the given order: ```shell -cds w xtravels/srv/events +cds w xtravels/srv/events --port 4006 ``` ```shell -cds w xtravels/srv/hotels +cds w xtravels/srv/hotels --port 4007 ``` ```shell -cds w xflights +cds w xflights --port 4005 ``` ```shell -cds w xtravels +cds w xtravels --port 4004 ``` +> [!note] Port Configuration +> Each service must run on a different port. Without explicit `--port` flags, all services would try to use the default port 4004 and fail with "address already in use" errors. + In the log output of each [`@agent`]-ified service, that is for `events`, `hotels`, and `travels`, we see the `cds.connect to 'llm'` taking place: ```zsh From 74a83b5a2d3548da76a1fd13e79a0f6081bd8d1d Mon Sep 17 00:00:00 2001 From: Vitaly Kozyura <58591662+vkozyura@users.noreply.github.com> Date: Mon, 5 Oct 2026 09:09:50 +0200 Subject: [PATCH 2/5] Apply suggestion from @danjoa Co-authored-by: Daniel Hutzel --- guides/ai/xtravels-sample.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/ai/xtravels-sample.md b/guides/ai/xtravels-sample.md index 780bbf3c6..c978ac5b6 100644 --- a/guides/ai/xtravels-sample.md +++ b/guides/ai/xtravels-sample.md @@ -107,7 +107,7 @@ Before using MCP services, install the MCP plugin in the xtravels project: ```shell cd xtravels -npm install @cap-js/mcp --save +npm add @cap-js/mcp ``` ### MCP-enable given Services From 9e52fc8bdb339afd0c53187a9968072458af457b Mon Sep 17 00:00:00 2001 From: Vitaly Kozyura <58591662+vkozyura@users.noreply.github.com> Date: Mon, 5 Oct 2026 09:10:04 +0200 Subject: [PATCH 3/5] Apply suggestion from @danjoa Co-authored-by: Daniel Hutzel --- guides/ai/xtravels-sample.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/guides/ai/xtravels-sample.md b/guides/ai/xtravels-sample.md index c978ac5b6..c4cc098b5 100644 --- a/guides/ai/xtravels-sample.md +++ b/guides/ai/xtravels-sample.md @@ -169,9 +169,6 @@ In case of the XTravels application we choose to not just [`@mcp`]-enable the ex CAP puts a main focus on [fast inner-loop development](../integration/inner-loops) and iterative testing, making it easy to quickly see the effects of changes in your services. This also holds true for MCP-enabled services, which we can test locally using local installations of [OpenCode](https://opencode.ai/), [Claude Code](https://claude.ai/), or any other MCP client. -> [!note] MCP Client Prerequisites -> MCP clients like OpenCode require an LLM API key to be configured before use. See your client's documentation for setup instructions. - > [!note] Different AI Client Behaviors > Different MCP clients may have different interaction patterns. The screenshots below show OpenCode's style. Your experience may vary with other clients. From 1c2d1a903f57e983af4cc378ce41752070cd4b4e Mon Sep 17 00:00:00 2001 From: Vitaly Kozyura <58591662+vkozyura@users.noreply.github.com> Date: Mon, 5 Oct 2026 09:10:35 +0200 Subject: [PATCH 4/5] Apply suggestion from @danjoa Co-authored-by: Daniel Hutzel --- guides/ai/xtravels-sample.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/guides/ai/xtravels-sample.md b/guides/ai/xtravels-sample.md index c4cc098b5..50dd66870 100644 --- a/guides/ai/xtravels-sample.md +++ b/guides/ai/xtravels-sample.md @@ -169,9 +169,6 @@ In case of the XTravels application we choose to not just [`@mcp`]-enable the ex CAP puts a main focus on [fast inner-loop development](../integration/inner-loops) and iterative testing, making it easy to quickly see the effects of changes in your services. This also holds true for MCP-enabled services, which we can test locally using local installations of [OpenCode](https://opencode.ai/), [Claude Code](https://claude.ai/), or any other MCP client. -> [!note] Different AI Client Behaviors -> Different MCP clients may have different interaction patterns. The screenshots below show OpenCode's style. Your experience may vary with other clients. - With the above changes, restart your CAP server in a terminal: ```shell From afc919e7000f8d0eb931f1499970643909bde4e7 Mon Sep 17 00:00:00 2001 From: Vitaly Kozyura <58591662+vkozyura@users.noreply.github.com> Date: Mon, 5 Oct 2026 09:11:13 +0200 Subject: [PATCH 5/5] Apply suggestion from @danjoa Co-authored-by: Daniel Hutzel --- guides/ai/xtravels-sample.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/guides/ai/xtravels-sample.md b/guides/ai/xtravels-sample.md index 50dd66870..d5406af15 100644 --- a/guides/ai/xtravels-sample.md +++ b/guides/ai/xtravels-sample.md @@ -175,9 +175,6 @@ With the above changes, restart your CAP server in a terminal: cds w xtravels ``` -> [!note] MCP Auto-wiring -> When `cds watch` starts, CAP automatically writes MCP server entries to your MCP client's configuration files (e.g., `~/.opencode/config.json` for OpenCode or `~/.claude.json` for Claude Code). These entries **persist after the server stops**. If you work with multiple CAP projects or change ports/services, you may need to manually clean up stale entries from these config files. - In a separate terminal, start OpenCode: ```shell