cayenne-reverse-engineer

cayenne-reverse-engineer

Import a database schema into a Cayenne DataMap by driving the CayenneModeler's reverse-engineering wizard through MCP. Cayenne 5.0 does not yet expose reverse engineering as a direct MCP tool, so the workflow launches the GUI and walks the user through the wizard.

Required reading

• ${CLAUDE_PLUGIN_ROOT}/references/project-layout.md — locate or create the project descriptor.
• ${CLAUDE_PLUGIN_ROOT}/references/dbimport-config.md — the field semantics behind every wizard screen, so you can explain options in user terms.
• ${CLAUDE_PLUGIN_ROOT}/references/mcp-tools.md — open_project tool reference and behavior when MCP is not connected.

Step 1 — Confirm scope

Ask the user (one question, only if not obvious from the request):

• Are they reverse-engineering into a new DataMap, or adding/updating entities in an existing DataMap?

Step 2 — Locate or create the project

Follow project-layout.md to find the existing cayenne-*.xml. If none exists, the user is starting from scratch:

• Either generate a minimal descriptor first (use cayenne-modeling's patterns — namespace http://cayenne.apache.org/schema/12/domain, project-version="12", one empty <map name="..."/> plus a sibling empty *.map.xml), or
• Tell the user to use File → New Project inside the Modeler once it's open.

The descriptor path needs to be absolute when passed to open_project.

Step 3 — Launch the Modeler

Call the MCP tool:

mcp__cayenne__open_project({ "projectPath": "<absolute path to cayenne-*.xml>" })

If the tool is not available (server not registered), surface cayenne-mcp-server/README.md and stop. Do not suggest mvn cayenne:cdbimport or any Gradle equivalent — those build plugins are out of scope.

If open_project returns a non-ok status, surface the error code and message; common ones are modeler_not_found, project_not_found, handshake_timeout. Don't retry blindly — diagnose first.

Step 4 — Walk the user through the wizard

The user now has the Modeler open. Give them the exact GUI sequence:

1. DataMap → DB Import tab
2. Data Source dialog:
   • JDBC Driver — e.g., org.postgresql.Driver
   • DB URL — full JDBC URL
   • User Name / Password — credentials
   • Cayenne Adapter (optional, autodetected for known DBs) — e.g., org.apache.cayenne.dba.postgres.PostgresAdapter
   • Click Test Connection, then Continue.
3. Configure screen — set table/column/procedure filters:
   • Include/exclude regex patterns under the relevant catalog/schema.
   • Table Types — usually leave at TABLE; add VIEW if the user wants views imported.
4. Naming screen:
   • Naming Strategy — usually the default (DefaultObjectNameGenerator).
   • Strip from Table Names — regex to strip a prefix like ^TBL_.
   • Default Package — Java package for generated ObjEntity classes.
   • Meaningful PK Tables — regex (or *) for tables whose PK columns should be exposed as ObjAttributes. Leave empty unless the user needs PK visibility.
5. Other Options — toggles for skipPrimaryKeyLoading, skipRelationshipsLoading, forceDataMapCatalog, forceDataMapSchema, useJava7Types. See dbimport-config.md for what each does; defaults are usually right.
6. Click Save then Run Import. The Modeler runs the import and reports a diff (added/changed/removed entities).

Explain options as the user asks — dbimport-config.md has the semantics. When unsure, recommend the default.

Step 5 — Confirm and follow up

Once the user reports the import is done and they've saved the project:

• Tell them to save the project in the Modeler (File → Save). The Modeler persists wizard settings as a <dbImport> block inside the DataMap for repeat runs.
• Hand off to cayenne-cgen to regenerate Java classes for the new/changed entities. Quote the DataMap name so the cgen skill can pass it to cgen_run.
• If the DB has columns that don't follow the user's preferred naming, recommend tweaking the naming strategy and re-running.

Anti-patterns

• Do not suggest mvn cayenne:cdbimport, the Gradle cdbimport task, or hand-running the cayenne-dbsync Java APIs. The Modeler GUI is the only supported execution path here.
• Do not try to hand-write a DataMap from a DB schema description as a substitute for the wizard — the wizard handles JDBC types, PK detection, FK relationships, and naming consistently. Hand-rolling produces subtle mistakes.
• Do not enable forceDataMapCatalog / forceDataMapSchema defensively. They suppress legitimate DB metadata and cause hard-to-debug issues in multi-catalog setups.
• Do not offer reverse engineering without MCP — if the server isn't connected, point at cayenne-mcp-server/README.md and stop.