This is an automated email from the ASF dual-hosted git repository. asf-gitbox-commits pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/cayenne.git
commit 54e7ff7400d904971e732d49e3e15790e6a3e5ae Author: Andrus Adamchik <[email protected]> AuthorDate: Tue May 19 16:35:47 2026 -0400 documenting MCP server --- .../src/docs/asciidoc/_cayenne-guide/part3.adoc | 21 ++++++ .../_cayenne-guide/part3/installingMcpServer.adoc | 88 ++++++++++++++++++++++ .../asciidoc/_cayenne-guide/part3/mcpTools.adoc | 67 ++++++++++++++++ .../asciidoc/_cayenne-guide/part3/overview.adoc | 19 +++++ .../src/docs/asciidoc/cayenne-guide.adoc | 2 + 5 files changed, 197 insertions(+) diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc new file mode 100644 index 000000000..36a28ad59 --- /dev/null +++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc @@ -0,0 +1,21 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to you under the Apache License, Version +// 2.0 (the "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 Unless required by +// applicable law or agreed to in writing, software distributed under the +// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR +// CONDITIONS OF ANY KIND, either express or implied. See the License for +// the specific language governing permissions and limitations under the +// License. + +== Agentic Coding + +include::part3/overview.adoc[] + +include::part3/installingMcpServer.adoc[] + +include::part3/mcpTools.adoc[] diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/installingMcpServer.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/installingMcpServer.adoc new file mode 100644 index 000000000..2af8b9546 --- /dev/null +++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/installingMcpServer.adoc @@ -0,0 +1,88 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to you under the Apache License, Version +// 2.0 (the "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 Unless required by +// applicable law or agreed to in writing, software distributed under the +// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR +// CONDITIONS OF ANY KIND, either express or implied. See the License for +// the specific language governing permissions and limitations under the +// License. + +=== Installing the Cayenne MCP Server + +The MCP server is a self-contained, stdio-based process that the AI client launches on demand. It is bundled with the platform-specific CayenneModeler and requires Java 21 or later on the system `PATH`. + +==== Finding the JAR + +As mentioned above, the MCP server jar is a part if the CayenneModeler download (available at https://cayenne.apache.org/download/). Its location depends on the install format: + +===== macOS + +[source] +---- +# <install-dir> is typically "/Applications", but it can be any other directory +<install-dir>/CayenneModeler.app/Contents/Resources/mcp/cayenne-mcp-server-<VERSION>.jar +---- + +===== Windows + +[source] +---- +<install-dir>\bin\cayenne-mcp-server-<VERSION>.jar +---- + +===== Linux / cross-platform + +[source] +---- +<install-dir>/bin/cayenne-mcp-server-<VERSION>.jar +---- + +==== Configuring AI clients + +The server communicates over stdio and is launched on demand by the client. In the snippets below, replace `/path/to/cayenne-mcp-server-<VERSION>.jar` with the actual jar path from the previous section. + +===== Claude Code + +By default `claude mcp add` registers the server for the current project only. Use `--scope user` to make it available across all projects for your OS user: + +[source,bash] +---- +# Current project only +claude mcp add cayenne -- java -jar /path/to/cayenne-mcp-server-<VERSION>.jar + +# All projects for the current user +claude mcp add cayenne --scope user -- java -jar /path/to/cayenne-mcp-server-<VERSION>.jar +---- + +===== Cursor + +Edit `~/.cursor/mcp.json` (global, all projects) or `.cursor/mcp.json` in your project (per-project): + +[source,json] +---- +{ + "mcpServers": { + "cayenne": { + "command": "java", + "args": ["-jar", "/path/to/cayenne-mcp-server-<VERSION>.jar"] + } + } +} +---- + +===== Codex + +Add a `[mcp_servers.cayenne]` entry to `~/.codex/config.toml`: + +[source,toml] +---- +[mcp_servers.cayenne] +command = "java" +args = ["-jar", "/path/to/cayenne-mcp-server-<VERSION>.jar"] +---- + diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/mcpTools.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/mcpTools.adoc new file mode 100644 index 000000000..131c07f35 --- /dev/null +++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/mcpTools.adoc @@ -0,0 +1,67 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to you under the Apache License, Version +// 2.0 (the "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 Unless required by +// applicable law or agreed to in writing, software distributed under the +// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR +// CONDITIONS OF ANY KIND, either express or implied. See the License for +// the specific language governing permissions and limitations under the +// License. + +=== MCP Tools + +The server currently exposes two tools. Your agent will discover them on its own, but it is useful to understand the capabilities and possible prompts. Both tools operate on a Cayenne project descriptor (a `cayenne-*.xml` file) and take absolute paths - agents should resolve relative paths against the current workspace before invoking. + +==== open_project + +Launches CayenneModeler with the given project file pre-loaded. The call is non-blocking; the server waits for the Modeler to confirm a successful project load via a short startup handshake, then returns. + +.Parameters +[cols="1,1,3", options="header"] +|=== +| Name | Required | Description +| `projectPath` | yes | Absolute path to the top-level Cayenne project descriptor (`cayenne-*.xml`). +|=== + +In most cases your agent knows where the project is, so a typical prompt that triggers this tool is just this: +[quote] +____ +open my Cayenne project in the Modeler +____ + +Though you can be more specific and indicate the exact project to open: +[quote] +____ +open the Cayenne project at @/path/to/cayenne-project.xml in the Modeler. +____ + + + +==== cgen_run + +Runs the Cayenne class generator (`cgen`) for a single DataMap inside the project, using the `cgen` configuration stored in the DataMap XML. The tool returns a JSON report describing which files were written, which were already up-to-date, and any errors encountered. + +.Parameters +[cols="1,1,3", options="header"] +|=== +| Name | Required | Description +| `projectPath` | yes | Absolute path to the top-level Cayenne project descriptor (`cayenne-*.xml`), not a DataMap file. +| `dataMap` | yes | Name of the target DataMap as it appears in the `<map name='...'>` element of the project descriptor. +|=== + +A typical agent prompt that triggers this tool: +[quote] +____ +regenerate Java classes for the `MyDataMap` DataMap in `/path/to/cayenne-project.xml`. +____ + +Or if you only have one project and one DataMap: +[quote] +____ +regenerate Java classes from Cayenne model +____ + diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/overview.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/overview.adoc new file mode 100644 index 000000000..133ee16fd --- /dev/null +++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/overview.adoc @@ -0,0 +1,19 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to you under the Apache License, Version +// 2.0 (the "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 Unless required by +// applicable law or agreed to in writing, software distributed under the +// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR +// CONDITIONS OF ANY KIND, either express or implied. See the License for +// the specific language governing permissions and limitations under the +// License. + +=== Overview + +AI coding agents such as Claude Code, Cursor, etc. can read and write Cayenne projects like any other Java codebase. For day-to-day API work — writing queries, manipulating an `ObjectContext`, etc. — you don't need anything Cayenne-specific. Prompt the agent the way you would for any other project. + +The Cayenne MCP (Model Context Protocol) server is what makes the agent _Cayenne-aware_ beyond plain source editing. It is a small stdio-based process that the AI client launches on demand and exposes a focused set of tools for operating on a Cayenne project descriptor. This chapter walks you through installing the server and explains the available tools. diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc index 11c152820..658849308 100644 --- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc +++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc @@ -45,6 +45,8 @@ include::_cayenne-guide/part1.adoc[] include::_cayenne-guide/part2.adoc[] +include::_cayenne-guide/part3.adoc[] + include::_cayenne-guide/part4.adoc[] include::_cayenne-guide/part5.adoc[]
