Skip to content

Commit 54e7ff7

Browse files
andrusandrus
committed
documenting MCP server
1 parent dc29372 commit 54e7ff7

5 files changed

Lines changed: 197 additions & 0 deletions

File tree

‎docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Licensed to the Apache Software Foundation (ASF) under one or more
2+
// contributor license agreements. See the NOTICE file distributed with
3+
// this work for additional information regarding copyright ownership.
4+
// The ASF licenses this file to you under the Apache License, Version
5+
// 2.0 (the "License"); you may not use this file except in compliance
6+
// with the License. You may obtain a copy of the License at
7+
//
8+
// https://www.apache.org/licenses/LICENSE-2.0 Unless required by
9+
// applicable law or agreed to in writing, software distributed under the
10+
// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
11+
// CONDITIONS OF ANY KIND, either express or implied. See the License for
12+
// the specific language governing permissions and limitations under the
13+
// License.
14+
15+
== Agentic Coding
16+
17+
include::part3/overview.adoc[]
18+
19+
include::part3/installingMcpServer.adoc[]
20+
21+
include::part3/mcpTools.adoc[]

‎docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/installingMcpServer.adoc‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
// Licensed to the Apache Software Foundation (ASF) under one or more
2+
// contributor license agreements. See the NOTICE file distributed with
3+
// this work for additional information regarding copyright ownership.
4+
// The ASF licenses this file to you under the Apache License, Version
5+
// 2.0 (the "License"); you may not use this file except in compliance
6+
// with the License. You may obtain a copy of the License at
7+
//
8+
// https://www.apache.org/licenses/LICENSE-2.0 Unless required by
9+
// applicable law or agreed to in writing, software distributed under the
10+
// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
11+
// CONDITIONS OF ANY KIND, either express or implied. See the License for
12+
// the specific language governing permissions and limitations under the
13+
// License.
14+
15+
=== Installing the Cayenne MCP Server
16+
17+
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`.
18+
19+
==== Finding the JAR
20+
21+
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:
22+
23+
===== macOS
24+
25+
[source]
26+
----
27+
# <install-dir> is typically "/Applications", but it can be any other directory
28+
<install-dir>/CayenneModeler.app/Contents/Resources/mcp/cayenne-mcp-server-<VERSION>.jar
29+
----
30+
31+
===== Windows
32+
33+
[source]
34+
----
35+
<install-dir>\bin\cayenne-mcp-server-<VERSION>.jar
36+
----
37+
38+
===== Linux / cross-platform
39+
40+
[source]
41+
----
42+
<install-dir>/bin/cayenne-mcp-server-<VERSION>.jar
43+
----
44+
45+
==== Configuring AI clients
46+
47+
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.
48+
49+
===== Claude Code
50+
51+
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:
52+
53+
[source,bash]
54+
----
55+
# Current project only
56+
claude mcp add cayenne -- java -jar /path/to/cayenne-mcp-server-<VERSION>.jar
57+
58+
# All projects for the current user
59+
claude mcp add cayenne --scope user -- java -jar /path/to/cayenne-mcp-server-<VERSION>.jar
60+
----
61+
62+
===== Cursor
63+
64+
Edit `~/.cursor/mcp.json` (global, all projects) or `.cursor/mcp.json` in your project (per-project):
65+
66+
[source,json]
67+
----
68+
{
69+
"mcpServers": {
70+
"cayenne": {
71+
"command": "java",
72+
"args": ["-jar", "/path/to/cayenne-mcp-server-<VERSION>.jar"]
73+
}
74+
}
75+
}
76+
----
77+
78+
===== Codex
79+
80+
Add a `[mcp_servers.cayenne]` entry to `~/.codex/config.toml`:
81+
82+
[source,toml]
83+
----
84+
[mcp_servers.cayenne]
85+
command = "java"
86+
args = ["-jar", "/path/to/cayenne-mcp-server-<VERSION>.jar"]
87+
----
88+

‎docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/mcpTools.adoc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Licensed to the Apache Software Foundation (ASF) under one or more
2+
// contributor license agreements. See the NOTICE file distributed with
3+
// this work for additional information regarding copyright ownership.
4+
// The ASF licenses this file to you under the Apache License, Version
5+
// 2.0 (the "License"); you may not use this file except in compliance
6+
// with the License. You may obtain a copy of the License at
7+
//
8+
// https://www.apache.org/licenses/LICENSE-2.0 Unless required by
9+
// applicable law or agreed to in writing, software distributed under the
10+
// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
11+
// CONDITIONS OF ANY KIND, either express or implied. See the License for
12+
// the specific language governing permissions and limitations under the
13+
// License.
14+
15+
=== MCP Tools
16+
17+
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.
18+
19+
==== open_project
20+
21+
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.
22+
23+
.Parameters
24+
[cols="1,1,3", options="header"]
25+
|===
26+
| Name | Required | Description
27+
| `projectPath` | yes | Absolute path to the top-level Cayenne project descriptor (`cayenne-*.xml`).
28+
|===
29+
30+
In most cases your agent knows where the project is, so a typical prompt that triggers this tool is just this:
31+
[quote]
32+
____
33+
open my Cayenne project in the Modeler
34+
____
35+
36+
Though you can be more specific and indicate the exact project to open:
37+
[quote]
38+
____
39+
open the Cayenne project at @/path/to/cayenne-project.xml in the Modeler.
40+
____
41+
42+
43+
44+
==== cgen_run
45+
46+
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.
47+
48+
.Parameters
49+
[cols="1,1,3", options="header"]
50+
|===
51+
| Name | Required | Description
52+
| `projectPath` | yes | Absolute path to the top-level Cayenne project descriptor (`cayenne-*.xml`), not a DataMap file.
53+
| `dataMap` | yes | Name of the target DataMap as it appears in the `<map name='...'>` element of the project descriptor.
54+
|===
55+
56+
A typical agent prompt that triggers this tool:
57+
[quote]
58+
____
59+
regenerate Java classes for the `MyDataMap` DataMap in `/path/to/cayenne-project.xml`.
60+
____
61+
62+
Or if you only have one project and one DataMap:
63+
[quote]
64+
____
65+
regenerate Java classes from Cayenne model
66+
____
67+

‎docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/overview.adoc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Licensed to the Apache Software Foundation (ASF) under one or more
2+
// contributor license agreements. See the NOTICE file distributed with
3+
// this work for additional information regarding copyright ownership.
4+
// The ASF licenses this file to you under the Apache License, Version
5+
// 2.0 (the "License"); you may not use this file except in compliance
6+
// with the License. You may obtain a copy of the License at
7+
//
8+
// https://www.apache.org/licenses/LICENSE-2.0 Unless required by
9+
// applicable law or agreed to in writing, software distributed under the
10+
// License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
11+
// CONDITIONS OF ANY KIND, either express or implied. See the License for
12+
// the specific language governing permissions and limitations under the
13+
// License.
14+
15+
=== Overview
16+
17+
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.
18+
19+
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.

‎docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@ include::_cayenne-guide/part1.adoc[]
4545

4646
include::_cayenne-guide/part2.adoc[]
4747

48+
include::_cayenne-guide/part3.adoc[]
49+
4850
include::_cayenne-guide/part4.adoc[]
4951

5052
include::_cayenne-guide/part5.adoc[]

0 commit comments

Comments
 (0)
⚡