# ajhcs/cameo-mcp-bridge architecture

> Architecture diagram of the GitHub repository ajhcs/cameo-mcp-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ajhcs/cameo-mcp-bridge
- Repository: https://github.com/ajhcs/cameo-mcp-bridge

## Overview

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.

Main entry points: [`plugin/src/com/claude/cameo/bridge/handlers`](https://github.com/ajhcs/cameo-mcp-bridge/tree/master/plugin/src/com/claude/cameo/bridge/handlers) (Handlers), [`mcp-server/cameo_mcp/server.py`](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/server.py) (MCP Server), [`mcp-server/cameo_mcp/client.py`](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/client.py) (HTTP Client), [`plugin/src/com/claude/cameo/bridge/HttpBridgeServer.java`](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/HttpBridgeServer.java) (HTTP Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_side["MCP Client Side"]
  node_mcp_client(("MCP Client<br/>external client"))
  node_mcp_server["MCP Server<br/>python MCP<br/>[server.py]"]
  node_client_bridge["HTTP Client<br/>python bridge client<br/>[client.py]"]
  node_verification["Verification<br/>python checks<br/>[verification.py]"]
  node_semantics["Semantic Rules<br/>python semantics"]
  node_remediation["Auto Remediation<br/>python planning"]
  node_methodology["Methodology<br/>workflow layer"]
end

subgraph group_bridge_runtime["Bridge Runtime"]
  node_plugin_entry["Plugin Entry<br/>java plugin"]
  node_http_server["HTTP Bridge<br/>java server"]
  node_handler_router["Handlers<br/>java routing layer"]
  node_edt_dispatcher["EDT Dispatch<br/>java concurrency boundary<br/>[EdtDispatcher.java]"]
  node_util_layer["Bridge Utils<br/>java shared util"]
  node_project_model["Project State<br/>handler family"]
  node_model_editing["Model Editing<br/>handler family"]
  node_presentation["Presentation<br/>handler family"]
  node_native_artifacts["Native Artifacts<br/>handler family<br/>[MatrixHandler.java]"]
  node_integration["Optional Integrations<br/>handler family"]
  node_macros{{"Macro Escape Hatch<br/>java macro bridge<br/>[MacroHandler.java]"}}
end

subgraph group_cameo_runtime["Cameo Runtime"]
  node_cameo_api[("Cameo APIs<br/>modeling api")]
end

node_mcp_client -->|"MCP requests"| node_mcp_server
node_mcp_server -->|"HTTP calls"| node_client_bridge
node_client_bridge -->|"localhost JSON"| node_http_server
node_http_server -->|"dispatch"| node_handler_router
node_handler_router -.->|"write boundary"| node_edt_dispatcher
node_handler_router -->|"project/session"| node_project_model
node_handler_router -->|"elements"| node_model_editing
node_handler_router -->|"diagrams"| node_presentation
node_handler_router -->|"artifacts"| node_native_artifacts
node_handler_router -->|"optional features"| node_integration
node_handler_router -.->|"escape hatch"| node_macros
node_project_model -->|"sessions"| node_cameo_api
node_model_editing -->|"model ops"| node_cameo_api
node_presentation -->|"presentation ops"| node_cameo_api
node_native_artifacts -->|"native artifacts"| node_cameo_api
node_integration -->|"licensed features"| node_cameo_api
node_macros -.->|"arbitrary API"| node_cameo_api
node_mcp_server -->|"read checks"| node_verification
node_mcp_server -->|"semantic checks"| node_semantics
node_mcp_server -->|"repair planning"| node_remediation
node_mcp_server -->|"workflow layer"| node_methodology
node_http_server -->|"serialization"| node_util_layer
node_client_bridge -->|"response shaping"| node_util_layer

click node_mcp_server "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/server.py"
click node_client_bridge "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/client.py"
click node_verification "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/verification.py"
click node_semantics "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/state_machine_semantics.py"
click node_remediation "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/auto_remediation.py"
click node_methodology "https://github.com/ajhcs/cameo-mcp-bridge/tree/master/mcp-server/cameo_mcp/methodology"
click node_plugin_entry "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/CameoMCPBridgePlugin.java"
click node_http_server "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/HttpBridgeServer.java"
click node_handler_router "https://github.com/ajhcs/cameo-mcp-bridge/tree/master/plugin/src/com/claude/cameo/bridge/handlers"
click node_edt_dispatcher "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/util/EdtDispatcher.java"
click node_util_layer "https://github.com/ajhcs/cameo-mcp-bridge/tree/master/plugin/src/com/claude/cameo/bridge/util"
click node_project_model "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/ProjectHandler.java"
click node_model_editing "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/ElementMutationHandler.java"
click node_presentation "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/DiagramHandler.java"
click node_native_artifacts "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/MatrixHandler.java"
click node_integration "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/TeamworkHandler.java"
click node_macros "https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/MacroHandler.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_client,node_mcp_server,node_client_bridge,node_verification,node_semantics,node_remediation,node_methodology toneBlue
class node_plugin_entry,node_http_server,node_handler_router,node_edt_dispatcher,node_util_layer,node_project_model,node_model_editing,node_presentation,node_native_artifacts,node_integration,node_macros toneAmber
class node_cameo_api toneMint
```

## Components

### MCP Client Side

Python-facing MCP surface and workflow logic.

- **MCP Client**: external client · Local AI client that issues MCP tool requests.
- [MCP Server](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/server.py): python MCP · StdIO MCP process that exposes the tool surface and orchestrates request handling. · `mcp-server/cameo_mcp/server.py`
- [HTTP Client](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/client.py): python bridge client · Translates MCP requests into local HTTP calls and shapes responses for clients. · `mcp-server/cameo_mcp/client.py`
- [Verification](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/verification.py): python checks · Read-side verification, semantic checks, proofing, and consistency review. · `mcp-server/cameo_mcp/verification.py`
- [Semantic Rules](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/state_machine_semantics.py): python semantics · Domain-specific checks for state machines and other model semantics. · `mcp-server/cameo_mcp/state_machine_semantics.py`
- [Auto Remediation](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/mcp-server/cameo_mcp/auto_remediation.py): python planning · Plans or performs corrective actions after verification failures. · `mcp-server/cameo_mcp/auto_remediation.py`
- [Methodology](https://github.com/ajhcs/cameo-mcp-bridge/tree/master/mcp-server/cameo_mcp/methodology): workflow layer · Bounded workflow packs, guidance, and review-packet generation. · `mcp-server/cameo_mcp/methodology`

### Bridge Runtime

Local Python server and embedded Java plugin that move requests into Cameo.

- [Plugin Entry](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/CameoMCPBridgePlugin.java): java plugin · Cameo plugin bootstrap that loads the bridge into the modeling JVM. · `plugin/src/com/claude/cameo/bridge/CameoMCPBridgePlugin.java`
- [HTTP Bridge](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/HttpBridgeServer.java): java server · Embedded local HTTP server that receives requests from the Python MCP layer. · `plugin/src/com/claude/cameo/bridge/HttpBridgeServer.java`
- [Handlers](https://github.com/ajhcs/cameo-mcp-bridge/tree/master/plugin/src/com/claude/cameo/bridge/handlers): java routing layer · Request routing layer that dispatches into focused handler families. · `plugin/src/com/claude/cameo/bridge/handlers`
- [EDT Dispatch](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/util/EdtDispatcher.java): java concurrency boundary · Moves writes onto the Swing EDT and wraps them in sessions for safety. · `plugin/src/com/claude/cameo/bridge/util/EdtDispatcher.java`
- [Bridge Utils](https://github.com/ajhcs/cameo-mcp-bridge/tree/master/plugin/src/com/claude/cameo/bridge/util): java shared util · Shared JSON, capability, snapshot, diff, and serialization helpers. · `plugin/src/com/claude/cameo/bridge/util`
- [Project State](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/ProjectHandler.java): handler family · Project, session, containment, and UI state coordination. · `plugin/src/com/claude/cameo/bridge/handlers/ProjectHandler.java`
- [Model Editing](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/ElementMutationHandler.java): handler family · Element queries, mutations, relationships, profiles, and specifications. · `plugin/src/com/claude/cameo/bridge/handlers/ElementMutationHandler.java`
- [Presentation](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/DiagramHandler.java): handler family · Diagrams, typed diagrams, labels, display state, and presentation repair. · `plugin/src/com/claude/cameo/bridge/handlers/DiagramHandler.java`
- [Native Artifacts](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/MatrixHandler.java): handler family · Matrices, generic tables, and relation maps as first-class Cameo artifacts. · `plugin/src/com/claude/cameo/bridge/handlers/MatrixHandler.java`
- [Optional Integrations](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/TeamworkHandler.java): handler family · Teamwork, DataHub, simulation, import/export, report wizard, variants, and probes. · `plugin/src/com/claude/cameo/bridge/handlers/TeamworkHandler.java`
- [Macro Escape Hatch](https://github.com/ajhcs/cameo-mcp-bridge/blob/master/plugin/src/com/claude/cameo/bridge/handlers/MacroHandler.java): java macro bridge · Groovy macro execution for edge-case or unsupported Cameo operations. · `plugin/src/com/claude/cameo/bridge/handlers/MacroHandler.java`

### Cameo Runtime

In-process Cameo APIs, model semantics, and presentation/native artifact subsystems.

- **Cameo APIs**: modeling api · OpenAPI, EMF, SessionManager, and presentation APIs inside the Cameo JVM.

## Connections

- MCP Client → MCP Server: MCP requests · Client sends tool invocations into the Python MCP server.
- MCP Server → HTTP Client: HTTP calls · Server translates tool calls into local bridge requests.
- HTTP Client → HTTP Bridge: localhost JSON · Python client talks to the embedded HTTP bridge over loopback.
- HTTP Bridge → Handlers: dispatch · Incoming requests are routed to focused handler families.
- Handlers → EDT Dispatch: write boundary · Mutation paths cross into the Swing EDT for session-safe execution.
- Handlers → Project State: project/session · Project state, containment, and UI state operations.
- Handlers → Model Editing: elements · Queries and mutations for model elements, relations, profiles, and specs.
- Handlers → Presentation: diagrams · Diagram creation, shaping, label repair, and presentation reads/writes.
- Handlers → Native Artifacts: artifacts · Matrices, tables, and relation maps are handled as native artifacts.
- Handlers → Optional Integrations: optional features · Probes and handlers for Teamwork, DataHub, simulation, export, and variants.
- Handlers → Macro Escape Hatch: escape hatch · Fallback route for arbitrary Groovy macro execution inside Cameo.
- Project State → Cameo APIs: sessions · Uses Cameo session and project APIs.
- Model Editing → Cameo APIs: model ops · Touches the model API for create/query/update/delete and relationship management.
- Presentation → Cameo APIs: presentation ops · Uses diagram and presentation APIs directly.
- Native Artifacts → Cameo APIs: native artifacts · Reads and creates actual Cameo matrices, tables, and relation maps.
- Optional Integrations → Cameo APIs: licensed features · Invokes optional Cameo capabilities when available.
- Macro Escape Hatch → Cameo APIs: arbitrary API · Macro execution runs with broad access inside the Cameo JVM.
- MCP Server → Verification: read checks · Server can invoke verification and proofing workflows on readback.
- MCP Server → Semantic Rules: semantic checks · Server applies domain-specific semantic validation.
- MCP Server → Auto Remediation: repair planning · Failures can be converted into remediation plans or actions.
- MCP Server → Methodology: workflow layer · MCP server exposes bounded methodology packs and review generation.
- HTTP Bridge → Bridge Utils: serialization · Bridge utilities normalize JSON, capabilities, snapshots, and diffs.
- HTTP Client → Bridge Utils: response shaping · Python client-side helpers structure responses for AI consumption.