ajhcs/cameo-mcp-bridge

1. Overall shape

This repository is a two-runtime bridge between MCP clients and a running CATIA Magic / Cameo Systems Modeler instance. The architecture is:

MCP client → Python MCP server → local HTTP/JSON bridge → Java plugin inside the Cameo JVM → Cameo OpenAPI / EMF / SessionManager.

2. Python MCP server

mcp-server/cameo_mcp is the MCP-facing layer. It defines the tool surface, translates MCP requests into HTTP calls, and post-processes responses into the structured shapes expected by AI clients. It also contains reusable client-side validation and verification logic, plus the methodology workflow layer.

3. Java Cameo plugin

plugin/src/com/claude/cameo/bridge is the in-process integration layer loaded into Cameo. It exposes an embedded HTTP server and routes requests into handler classes. This layer is the only code that directly touches the Cameo runtime and model API.

4. Request flow and threading boundary

Read operations are handled as HTTP requests and can execute on the server thread pool. Write operations cross an important boundary: they are dispatched onto the Swing EDT through EdtDispatcher and wrapped in Cameo sessions for undo/redo safety. That separation is central to the system’s correctness.

5. Handler-based backend

The plugin is organized into focused handler families rather than a single monolith. Major handler groups cover project/session state, element queries and mutation, relationships, diagrams, matrices, relation maps, UI state, validation, report generation, import/export, teamwork, DataHub, simulation, specifications, macros, and optional extension probes.

6. Model-editing subsystem

The core modeling path supports creating, querying, updating, deleting, and relating UML/SysML elements. It also handles stereotypes, tagged values, profiles, and specification writes. This is the main “authoring” subsystem and is designed to preserve Cameo semantics rather than just manipulating raw JSON.

7. Diagram and presentation subsystem

A large part of the bridge is about Cameo’s presentation layer: creating diagrams, placing shapes, drawing paths, changing display properties, repairing labels, pruning autogenerated visuals, and reading back presentation state. This subsystem is distinct from pure model editing because it operates on diagram objects and presentation IDs, not just model elements.

8. Native artifacts subsystem

The bridge exposes Cameo-native matrices, generic tables, and Relation Maps as first-class artifacts. These are not simulated abstractions; the handlers read and create the actual native artifacts and their settings, rows, columns, graph settings, and renderable evidence.

9. Evidence, verification, and repair

The Python layer adds lightweight verification and semantic checks on top of bridge readback. There are dedicated flows for diagram visual checks, matrix consistency, state-machine semantics, requirement quality, cross-diagram traceability, auto-remediation planning, and proofing. These are designed as read/preview/plan layers before mutation.

10. Methodology workflow subsystem

mcp-server/cameo_mcp/methodology implements bounded OOSEM-style methodology packs, artifact recipes, guidance, validation, and review-packet generation. This sits above low-level model operations and treats model artifacts as structured evidence for workflow conformance.

11. Optional integration and probe-first boundaries

Teamwork, DataHub, simulation, report generation, variants, and extension-specific features are exposed conservatively. The architecture favors capability probes, previews, and refusal payloads before writes. This makes optional Cameo products and licenses explicit dependencies rather than hidden assumptions.

12. Macro escape hatch

Groovy macro execution is a deliberate escape hatch for cases the structured handlers do not cover, especially nested presentation edits and edge-case Cameo API behavior. It bypasses most safety constraints and runs inside the Cameo JVM, so it is architecturally separated from the normal structured tool path.

13. Serialization and state helpers

The Java util package contains shared infrastructure for JSON parsing, serialization of elements/presentations/properties/validation, capability detection, snapshot storage, tagged-value coercion, and diffing. These utilities normalize Cameo-specific objects into transportable JSON for the Python layer.

14. Build, deployment, and local runtime

The plugin is built with Gradle/Java 17 and deployed into the Cameo installation. The Python server is packaged independently and runs on stdio as an MCP process. The installer (install.sh) ties these together, deploying the plugin and registering the MCP server with the client.

15. Trust and security boundary

The bridge is explicitly local-only. The HTTP server binds to localhost, does not authenticate, and the macro tool can execute arbitrary code inside the Cameo JVM. For diagramming purposes, the critical boundary is between trusted local tooling and a full-privilege modeling application, not between tiers in a typical internet-facing web service.