Archi MCP Server

An Eclipse PDE plugin for Archi that exposes ArchiMate models through the Model Context Protocol (MCP), enabling LLMs to query, analyse, and modify enterprise architecture models through natural language.

What It Does

Archi MCP Server embeds an HTTP server inside Archi that speaks MCP. Once running, any MCP-compatible LLM client (Claude, Cline, LM Studio, etc.) can connect and interact with the currently open ArchiMate model — asking questions, searching elements, traversing relationships, composing view diagrams, and even creating or modifying model content.

The server provides 70 MCP tools across querying, searching, creating, layout, routing, assessment, batch operations, images, specializations, and more — plus 14 MCP resources with ArchiMate reference material, workflow guides, and a viewpoint recipe library for LLMs.

Example conversation:

You: “What applications support the Customer Portal capability?”

LLM: Searches elements, traverses relationships, and returns: “7 applications support Customer Portal: OrderService, PaymentGateway, …”

Requirements

LLM model size recommendation: 8B+ parameters minimum, 14B+ for reliable tool calling, 70B+ for complex view composition workflows.

Installation

1. Download the latest .archiplugin from the Releases page (or the bin/ directory for pre-built artifacts)
2. In Archi: Help > Manage Plug-ins > Install New… or copy to Archi’s dropins/ folder
3. Restart Archi

Getting Started

1. Start the Server

Open an ArchiMate model in Archi, then:

Menu: MCP Server > Start MCP Server

The MCP Server entry in Archi’s menu bar has three items:

Server behaviour (port, bind address, TLS, authentication, …) is configured separately under Window > Preferences > MCP Server — see Configuration. The default endpoint is http://127.0.0.1:18090.

2. Configure Your LLM Client

Claude Code (CLI)

In your project’s .mcp.json or ~/.claude.json:

{
  "mcpServers": {
    "archi": {
      "type": "http",
      "url": "http://127.0.0.1:18090/mcp"
    }
  }
}

Or via the CLI:

claude mcp add --transport http archi http://127.0.0.1:18090/mcp

Claude Desktop

Claude Desktop does not natively support Streamable HTTP, so a proxy is required. Install uv (a single Rust binary), then add to your claude_desktop_config.json:

Windows:

{
  "mcpServers": {
    "archi": {
      "command": "C:\\Users\\YOUR_USER\\.local\\bin\\uvx.exe",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "http://127.0.0.1:18090/mcp"]
    }
  }
}

macOS:

{
  "mcpServers": {
    "archi": {
      "command": "uvx",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "http://127.0.0.1:18090/mcp"]
    }
  }
}

Cline / Other MCP Clients

Point your MCP client at the Streamable-HTTP endpoint:

http://127.0.0.1:18090/mcp

SSE transport is also available at /sse for older clients.

3. Start Querying

With the server running and your LLM client connected, you can ask questions in natural language:

• “Give me an overview of this architecture model”
• “Find all Application Services in the model”
• “What does the Order Processing component depend on?”
• “Show me the relationships between the CRM and ERP systems”
• “Create a new view showing the payment processing flow”
• “Auto-layout and route the connections on this view”

Configuration

Access via Window > Preferences > MCP Server in Archi.

TLS / HTTPS

The server supports optional TLS encryption. To enable:

1. In preferences, check Enable TLS (HTTPS)
2. Click Generate Self-Signed Certificate to create a keystore automatically
3. Restart the server — the endpoint changes to https://127.0.0.1:18090

Clients must trust the self-signed certificate. For curl testing, use the -k flag. For LLM clients, import the certificate into the client’s trust store or the JVM cacerts.

The keystore password (whether you type it or generate it with the button) is stored in your OS keychain via Equinox secure storage — the same store the bearer token and Archi itself use — not in the plaintext preference file. If you had a keystore password set in an earlier version, it is migrated automatically on first start.

Enabling authentication (bearer token)

By default the server requires no authentication — anything that can reach the port can call the tools, which is why the default bind is loopback only. If you bind to a non-loopback address, or simply want a secret required even on loopback, enable an opt-in bearer token:

1. In Window > Preferences > MCP Server > Authentication, check Enable bearer-token authentication. A 256-bit token is generated automatically on first opt-in and stored in your OS keychain (via Equinox secure storage — no separate password to manage).
2. Click Copy to copy the token, or Generate / Regenerate token to roll it (regenerating invalidates clients still using the old token).
3. Restart the server. Every request to /mcp and /sse must now send Authorization: Bearer ; a missing, malformed, or wrong token gets 401.

Configure your clients to send the header:

Claude Code (CLI):

claude mcp add --transport http archi http://127.0.0.1:18090/mcp --header "Authorization: Bearer "

Claude Code (.mcp.json / ~/.claude.json):

{
  "mcpServers": {
    "archi": {
      "type": "http",
      "url": "http://127.0.0.1:18090/mcp",
      "headers": { "Authorization": "Bearer " }
    }
  }
}

Claude Desktop (via mcp-proxy) — pass the header through the proxy:

{
  "mcpServers": {
    "archi": {
      "command": "uvx",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "--headers", "Authorization", "Bearer ", "http://127.0.0.1:18090/mcp"]
    }
  }
}

curl (testing):

curl -X POST http://127.0.0.1:18090/mcp -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Authentication is off by default — existing configs without an Authorization header keep working unchanged until you enable it. On a non-loopback bind, also enable TLS so the token is not sent in cleartext.

Security model

The server exposes mutating and file-touching tools over HTTP, so the trust boundary is worth understanding. SECURITY.md states what the server protects against by default (loopback bind, Origin/Host validation, request/session/image resource limits, UTF-8 request-body enforcement, the human-owned approval gate) versus what is your responsibility as the operator (transport encryption, client authentication, securing a non-loopback bind), and how to report a vulnerability. Read it before binding off-loopback or pointing an agent at untrusted input.

Available Tools

The server exposes 70 MCP tools organised into functional categories.

Query & Model Inspection (6 tools)

Search & Discovery (4 tools)

Element & Relationship Creation (4 tools)

Element, Relationship, View & Model Updates (4 tools)

ArchiMate Specializations (5 tools)

Specializations are IS-A subtypes of ArchiMate concept types (e.g. “Microservice” is a kind of ApplicationComponent, “Cloud Server” is a kind of Node). Use them to classify the kind of thing an element is — not for per-instance attributes like environment or version. See archimate://reference/archimate-specializations for the full guide.

View Composition (9 tools)

All view-composition tools that place a new visual object (add-to-view, add-group-to-view, add-note-to-view, add-view-reference-to-view, add-image-to-view) and update-view-object accept the full visual styling surface: fill / line / font colour, opacity, line width, line style (solid / dashed / dotted / none), typography (fontName, fontSize, fontStyle), gradient, deriveLineColor, outlineOpacity, figureType (rectangular / tabbed), textAlignment, verticalTextAlignment, plus note-specific borderType (dogear / rectangle / none). Existing calls are byte-identical; supply only the fields you want to set. Every one of these fields reads back through get-view-contents, so a styling mutation can be verified after the write.

Title alignment now matches the palette on the three types where Archi’s own default is a fixed constant. Archi’s diagram factory stamps a type’s UI-provider defaults onto anything drawn from the palette; this server builds objects straight from the EMF factory, which stamps nothing, so an ArchiMate Grouping, a native group and a note used to come out centre where a hand-drawn one is left — on a 400 px box, a title starting a few pixels from the edge versus one sitting ~170 px away. Those three types are now stamped left at creation, before any styling is applied, so an object created with no styling at all matches the palette while an explicit textAlignment still wins. Scope: a plain ArchiMate element’s default is derived by Archi from a user preference rather than a constant, so this server leaves it at centre and a host whose preference was changed can still differ — pass textAlignment explicitly when the alignment matters. Connections, images and view references already carried their own providers’ values and are untouched. clone-view copies both textAlignment and verticalTextAlignment, so a cloned object keeps its title band rather than silently reverting to top.

When add-to-view or add-group-to-view nests a child inside a container whose fill colour you have not explicitly set, the parent’s fill auto-recedes to a subtle backdrop (#F4F4F4) so the nesting reads as depth instead of a flat block. The recession is provenance-gated and idempotent (only an unauthored fill is touched; an explicitly coloured container is left untouched), rides the placement as one undo unit, and excludes the root view. Pass recede: false to suppress it for a call.

A view object can also anchor to a target container via update-view-object, recording an {anchorTarget, anchorEdge, dx, dy} so its position resolves from the target’s current bounds at commit time rather than a frozen snapshot — edge below (default) tracks the target’s growing bottom, above/right/left the corresponding edge. When a later mutation moves or grows the target, every anchored object is repositioned within the same undo unit. Target and object must share a coordinate space; self-anchors and cross-space anchors are rejected. add-note-to-view’s content-relative placement uses the same edge resolver.

View Cleanup (2 tools)

Layout & Routing (11 tools)

LLM agents: Fetch archimate://prompts/routing-preconditions-checklist before invoking auto-route-connections or auto-layout-and-route on any non-trivial view. The routing pipeline cannot recover from missing preconditions — it can only route the geometry the agent has set up. The spacing convenience tools self-terminate honestly: if a view is provably too dense for spacing to fix they return terminationReason: density_floor_reflow_required and offer a user-consentable structural reflow — surface that to the user instead of looping the spacing tools.

Layout Assessment & Analysis (2 tools)

Metric acronyms below — M1–M6, R8, parallelConnectionGap_V_p10 (V_p10), HPQ — are defined in the glossary.

View Operations (1 tool)

Folder Management (5 tools)

Deletion (4 tools)

Export (1 tool)

Images (2 tools)

Batch & Mutation Control (4 tools)

Undo / Redo (2 tools)

Approval Workflow (1 tool)

The approval gate is owned by the human in Archi (a desktop toggle), not by the agent. The MCP surface exposes only a read-only observation tool — the agent can see that changes are gated but cannot enable/disable the gate or approve its own queued changes.

Session Management (2 tools)

Reference & Guidance (1 tool)

Response Control

All query tools support response optimisation parameters:

• Field selection: fields param with presets (minimal, standard, full) or custom field arrays
• Field exclusion: exclude param to omit specific fields
• Pagination: Automatic for large result sets, with cursor-based continuation

How far a preset reaches on get-view-contents. A view response carries seven arrays, and fields routes only two of them — the element and relationship rows — through its verbosity filter. visualMetadata, connections, groups, notes and images go in whole at every preset, and on a view carrying connections those five are usually the larger half, so exclude rather than fields is normally the parameter that moves the response size. Both apply to format: "json" and format: "graph" only: format: "summary" and format: "tree" return before the field selector runs, so neither parameter reaches anything there.

MCP Resources

The server provides 14 reference resources accessible to LLM clients.

They are published three ways so that every client can reach them: as static MCP resources, as the equivalent resource templates (archimate://prompts/{name}, archimate://reference/{name}, archimate://recipes/{name}), and through the get-guidance tool. Clients that do not expose MCP resource reads to the model can call get-guidance with no arguments to list every URI, or with a uri to read one. See MCP Resources for detail.

Prompts

References

Viewpoint Recipes

A progressive-disclosure recipe library for laying out non-conventional ArchiMate viewpoints. Fetch the index first; it states the invariant build sequence once, routes conventional viewpoints (layered, landscape, hierarchy, information structure) to the view-patterns principles, and points non-conventional viewpoints to a single full recipe page with the topology block to match.

Prompt Library

Separate from the MCP resources above (which an LLM client fetches over the protocol), the top-level prompts/ folder holds ready-to-use prompts you paste into an agent session that has the Archi MCP tools connected. Each file is self-contained: replace any {{PLACEHOLDER}} tokens and run.

archimate-model-to-pdf-report.md also ships with an optional reference implementation, prompts/archimate-model-to-pdf-report.py — a standalone generator that talks to the MCP server over its loopback HTTP endpoint, harvests the model, exports each view and renders the PDF in one command, with --full for complete element and relationship coverage including concepts placed on no view. It needs only the Python standard library plus the weasyprint CLI.

Two of these are also distributed as Claude Code slash commands, each embedding a self-contained copy of its prompt plus an argument-parsing preamble: repo-to-archimate-model.md as /repo-to-archi (adding a repository argument and a clone step), and drawio-to-archimate-model.md as /drawio-to-archi (taking the diagram source — a path, pasted mxGraph XML or a Confluence page — the layout mode, an optional companion document and optional icon packages). The command copies do not auto-update — prompts/ is the source of truth, so re-sync after editing a prompt here. For both commands the sync is mechanical: run tools/sync-drawio-command.sh or tools/sync-repo-command.sh to regenerate a copy, or --check to fail a build when it has drifted; CI gates both. /repo-to-archi additionally rewrites the prompt’s {{REPO_PATH}}/{{REPO_REF}} placeholders into its $ARGUMENTS form, and its generator refuses to emit a copy in which any placeholder survived.

Mutation Safety

All write operations integrate with Archi’s CommandStack, making every mutation undoable via Ctrl+Z in Archi or the undo / redo tools.

Verbatim-store validation. A name, label, view-object text, or labelExpression containing a well-formed HTML/XML entity token (&, <,  , &, …) is rejected with a corrective hint rather than silently stored as the escaped literal — the recurring & footgun. Bare ampersands and non-entity text (R&D, A & B, ``, ${name} & ${property:x}) are accepted and stored byte-for-byte. The rule covers create-* / update-* / add-* and their bulk-mutate equivalents.

Integrity guards hold on deferred paths. A precondition checked when a command is built is worthless once the command is queued, because a sibling operation in the same batch can invalidate it before the command runs. Folder cycles, view-hierarchy and folder-layer placement, and specialization usage are therefore re-checked at execute time, which makes them path-agnostic — the same guard protects the immediate, batch, bulk and approval paths. A guard that trips declines the single operation with a named reason (surfaced in the batch summary and in bulk-mutate’s skippedOperations) instead of proceeding: a folder move that would form a containment cycle, for instance, previously threw nothing and left the affected folders unreachable from the model root. A declined nested folder is also protected from its own ancestor, so an outer cascade cannot remove by containment what an inner decline just saved. The same rule covers the container a create or a placement targets: create-view, create-folder and clone-view resolve a folder when the request is prepared and create into it later, and add-to-view resolves a parent container the same way — so an object whose destination was deleted earlier in the same request is now declined rather than created unreachable from the model root (really written, gone on reload, and reported as a success). A view-nesting parentId belonging to a different view is rejected with it, as are the connections a placement draws for itself: add-to-view with autoConnect and auto-connect-view both scan the view at prepare time, so a preceding remove-from-view could otherwise leave a connection joined to a detached endpoint.

Approval mode adds a human-in-the-loop gate that the human owns — the agent operates tools but can never move the gate or approve its own changes:

Human toggles "Approval Mode" ON in Archi (MCP Server menu)
  → agent's mutations queue as "pending" (not applied)
  → agent calls list-pending-approvals → sees what's gated, tells the user to confirm in Archi
  → human approves/rejects in Archi → apply, or discard

The toggle lives only on the human side: there is no MCP tool to enable/disable approval or to approve a proposal. Your choice is remembered across restarts (stored in MCP preferences); a fresh install defaults to GATED (fail safe). Turning the gate off requires a confirmation in Archi; turning it on is a single click. Approval mode is a single global switch (one human, one desktop, one gate), and the agent can read the current state via get-model-info (approvalMode).

Pending Approvals view. When approval mode is on, you review and apply the agent’s queued changes in the Pending Approvals dock view inside Archi. Open it from Window → Show View → MCP Server → Pending Approvals, or from the MCP Server → Pending approvals (N) menu item (which also shows the live count). Each gated tool-call — including a whole bulk-mutate — is one card, showing a plain-language effect rollup with destructive counts (deletes/removals) called out in amber. Show changes expands the card to named, verb-prefixed rows (deletes hoisted to the top) with a Technical details disclosure for the raw parameters. Approve applies the change (a card containing a delete stays disabled until you expand it once); Reject discards it with no change to the model. Toolbar Approve all safe clears the purely-additive cards in one click, and Approve all ⚠ drains everything after one confirmation that names the deletion count. New gated changes appear live without a refresh.

The card’s effect text is generated by the server from the model’s own truth, so you can decide from the card alone without opening Technical details: relationships name both endpoints (Create ServingRelationship: 'Payment Gateway' → 'Fraud Engine', and a delete adds its cascade), a delete-view or delete-folder card shows the blast radius the agent was given ((cascade: 11 view connections, 1 view reference), (force cascade: 1 view)) rather than the bare target id, and a bulk-mutate card’s rows are named per operation (+ Create "Payment Gateway" (ApplicationComponent), ↔ Connect "Payment Gateway" → "Fraud Engine" (ServingRelationship)). Agents may pass an optional intent on begin-batch or bulk-mutate (a plain-language “why”); when present it shows as a quiet agent's note: line below the effect — it never replaces or outranks the server effect, and an empty or generic note is dropped. Effect is non-spoofable server ground truth; intent is a separate, lower-trust claim the server never depends on.

The card describes the whole write, not part of it. Everything you see on a card — the headline sentence, the expanded rows and the Technical details disclosure — is derived from one map the server builds when the change is proposed, and that map is also what an agent reads back through list-pending-approvals. Two things follow, and both are now enforced rather than maintained by hand. Every parameter the approval will apply is in that map: a tool that accepts a parameter and writes it must disclose it, so you are never authorising an aspect of the change the card kept quiet about. A contract test parses every proposal site in the server and fails the build unless each one is complete or carries a registry line naming the exact parameters it exempts and why. And the card’s own sentence names the aspects that will change, derived from that same map rather than written by hand: renaming a box is announced as a rename, restyling a connection is not announced — or validated — as a reroute, and a call that discloses nothing says so instead of claiming a change it will not make. Under-disclosure hides a write; over-disclosure invents one, and the card is held to both ends.

The gate refuses rather than surprising you. The card is built when the change is proposed, while the command that runs is rebuilt against the current model at approve — so if the blast radius has grown in between (contents dragged into a folder already proposed for a force-delete, say), approval is refused and both numbers are named, instead of deleting five things against a card that said two. A refusal raised while rebuilding is now surfaced with its own reason and remedy (FOLDER_NOT_EMPTY … “Use force: true to cascade-delete all contents”) rather than the generic “a targeted object was changed or removed”, and Approve All reports that same reason when it stops instead of guessing. Cards also say which kind of gate you are looking at: most proposals re-run their preparation against the current model when you click Approve, but fourteen — the layout, routing and bulk-mutate passes — apply the exact compound you reviewed, because re-running a layout can legitimately produce a different result from the one on the card.

Batch mode groups mutations into atomic transactions:

begin-batch()
  → create-element(...)
  → create-relationship(...)
  → add-to-view(...)
end-batch()
  → All succeed together or all roll back

A batch can build on what it has already queued. Inside one begin-batch / end-batch window you can create a view and add objects to it, create an element and place it on that view, update a view object the same batch created, use a container the same batch created as a parentId, and anchor to an object the batch has queued but not yet written — from bulk-mutate running inside the batch as well as from the standalone tools. Every parent-fit cascade is measured against one shared same-batch geometry, so two independently-queued cascades can no longer emit competing absolute resizes of the same grandparent, and a queued size survives a later pass over the same view. Editing the same object twice in one batch applies only the fields each edit names — and a second edit that changes only a label or styling no longer discards bendpoints the first edit supplied. Where an id genuinely cannot be resolved the error names the mechanism — that the object exists but is owned by the open batch — rather than reporting it as not found.

That covers the whole script an agent runs to draw a view in one unit of work. add-connection-to-view resolves all four ids it takes (both endpoints, the relationship and the view), so a batch can place two elements and connect them; apply-view-layout resolves all three of its (the view, each positioned view object, each connection), so the result can be laid out before the batch ends; add-view-reference-to-view resolves the referenced view as well as the host; and update-view-connection can update a connection the same batch added. A queued endpoint is scoped to the view the connection lands on, so a batch cannot draw a connection whose two ends sit on different diagrams. Tools that update, delete or re-file a concept still report a queued id as not found — the standalone call inside the same batch is equally blind, because both callers share one prepare.

Troubleshooting

Server won’t start

• Check if port 18090 is already in use: lsof -i :18090
• Verify the bind address in preferences is valid

LLM client can’t connect

• Confirm the server is running (menu shows “Stop MCP Server”)
• Verify the port matches your client config
• Test connectivity: curl -X POST http://127.0.0.1:18090/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Model appears empty

• Ensure an ArchiMate model is open in Archi before connecting
• If the model was opened after the session started, reconnect the LLM client

Mutations fail with validation error

• Check the archiMateReference field in the error — it cites the relevant ArchiMate spec section
• Use search-and-create instead of create-element to avoid duplicates

TLS connection issues

• Verify the keystore file exists and the password is correct
• For self-signed certificates, ensure the client trusts the certificate or use -k with curl

Troubleshooting: secure storage (“Secure storage unavailable” when saving the token or keystore password)

The bearer token and the TLS keystore password are stored in Equinox secure storage, encrypted under an OS-protected master password (the macOS Keychain on Mac, the Windows Credential Store / DPAPI on Windows). If that OS-protected master password entry is lost or locked, saving fails with “Secure storage unavailable.” This is an environment/credential-store state issue, not a data problem — the app never falls back to storing the secret in cleartext, and any value already configured is left untouched. (On macOS the underlying error in the log reads SecurityException: Could not obtain password. Result: -25300; on Windows it surfaces as a StorageException reporting the master password could not be obtained.)

To recover, reset secure storage so Equinox can create a fresh master password:

1. Quit Archi.
2. Move aside the secure-storage file (a backup, so it’s reversible). It lives in the Archi instance area:
   • macOS:

     mv ~/Library/Application\ Support/Archi/secure_storage \
        ~/Library/Application\ Support/Archi/secure_storage.bak
     

   • Windows (PowerShell):

     Move-Item "$env:APPDATA\Archi\secure_storage" "$env:APPDATA\Archi\secure_storage.bak"
     

   If the path differs on your setup, the exact location is shown in the .metadata/.log file referenced below.
3. Restart Archi. Equinox recreates the store automatically (you may get a one-time OS prompt to allow access to the Keychain / Credential Store — allow it).
4. Re-enter any secrets that lived in the old store: the bearer token (Generate / Regenerate in preferences), the TLS keystore password (re-type it or use Generate Self-Signed Certificate), and — if you use them — any other Archi credentials (e.g. coArchi model-repository logins).

Note: Archi (unlike the full Eclipse IDE) does not expose the Error Log view in its menus on any platform. To read the full stack trace, open the .metadata/.log file inside your Archi instance area directly (~/Library/Application Support/Archi/.metadata/.log on macOS, %APPDATA%\Archi\.metadata\.log on Windows).

---

Developer Guide

The following sections are for developers who want to fork, extend, or contribute to the plugin.

For comprehensive technical documentation covering architecture internals, coordinate model, routing pipeline, and extension patterns, see docs/. Metric acronyms and routing terms used throughout this README (M1–M6, R8, parallelConnectionGap_V_p10, HPQ, corridor, clearance, perimeter) are defined in the glossary.

Project Structure

arch-mcp-server/
├── net.vheerden.archi.mcp/          # Main plugin bundle
│   ├── META-INF/MANIFEST.MF         # OSGi bundle configuration
│   ├── plugin.xml                    # Eclipse extension points
│   ├── src/net/vheerden/archi/mcp/
│   │   ├── McpPlugin.java           # Plugin lifecycle & preferences
│   │   ├── server/                   # Jetty + MCP SDK wiring
│   │   ├── handlers/                 # MCP tool implementations (19 handler classes)
│   │   ├── model/                    # EMF model access layer
│   │   │   ├── geometry/             # Geometry utilities
│   │   │   └── routing/              # Connection routing pipeline
│   │   ├── search/                   # Full-text search engine
│   │   ├── response/                 # Response formatting & DTOs
│   │   ├── registry/                 # Tool & resource registries
│   │   ├── session/                  # Session management & caching
│   │   ├── logging/                  # SLF4J to Eclipse ILog bridge
│   │   └── ui/                       # Preferences, menus, startup
│   ├── resources/                    # MCP resource content files
│   └── lib/                          # Bundled dependencies
│       ├── mcp-sdk/                  # MCP Java SDK 0.17.2
│       ├── jetty/                    # Jetty 12.0.18 (ee10)
│       ├── jackson/                  # Jackson 2.16.1
│       ├── elk/                      # Eclipse Layout Kernel 0.11.0
│       └── slf4j/                    # SLF4J 2.0.11
├── net.vheerden.archi.mcp.tests/    # Test fragment (OSGi)
└── README.md

Architecture Layers

The codebase enforces strict layer boundaries to keep concerns separated:

┌─────────────────────────────────────────────────────┐
│  Layer 1 — Protocol          server/, registry/     │
│  Only MCP SDK + Jetty types. No EMF imports.        │
├─────────────────────────────────────────────────────┤
│  Layer 2 — Handlers          handlers/              │
│  DTOs + ArchiModelAccessor interface only.           │
│  No EMF or SWT imports.                             │
├─────────────────────────────────────────────────────┤
│  Layer 3 — Model             model/                 │
│  ONLY package that imports EMF / ArchimateTool.     │
│  Returns DTOs, never EObjects.                      │
├─────────────────────────────────────────────────────┤
│  Layer 4 — UI                ui/                    │
│  SWT/Eclipse UI only. Preferences, menus, status.   │
│  Never blocks Jetty threads.                        │
└─────────────────────────────────────────────────────┘

Key rule: Handlers never see EMF objects. All model access goes through the ArchiModelAccessor interface, which returns DTOs.

Key Architecture Decisions

Transport

• Dual transport: Streamable-HTTP (/mcp) + SSE (/sse) for backward compatibility
• Each transport gets its own McpSyncServer instance
• HttpServletStreamableServerTransportProvider and HttpServletSseServerTransportProvider both extend HttpServlet

Threading

• Reads: Direct EMF access from Jetty threads (thread-safe for read-only)
• Mutations: Dispatched to the SWT UI thread via Display.syncExec() for CommandStack consistency
• UI thread is never blocked by read operations

Response Envelope

Every tool response follows a standard structure:

{
  "result": { },
  "nextSteps": ["Use get-relationships to explore connections", "..."],
  "_meta": { "totalCount": 42, "isTruncated": false, "durationMs": 12 }
}

Effective State

A mutating tool’s success response reports what the model now holds, never the values the caller passed in. This matters because Archi silently auto-fits a container to its children and cascades a fit up the containment chain, so a requested width / height / x / y may not survive the write — and the client is an agent that cannot see the canvas, so the response is its only ground truth. Geometry is re-read after the write (effectiveBounds), a connection’s styling, bendpoints and anchor points are re-read with it (effectiveConnection), an ArchiMate concept’s own state is re-read beside them (effectiveRelationship / effectiveElement, which carry the semantic attributes and documentation a bulk caller can change), an entity’s reported name is re-read once the whole call has been applied (entityName, so a rename or a clear is confirmed by the value the model ends up holding), and the collateral is named rather than counted: resizedAncestors and resizedGroups carry the containers a call grew with their new rectangles, nestedContainersFitted carries the descendant containers a recursive pass re-fitted, resizedElements carries the leaf children a layout pass re-sized without descending into them, and movedObjects carries the anchored children it displaced with their new positions. A count or a flag on its own does not satisfy this — resizedCount: 3 says something moved and leaves the agent unable to say where — and a field named as an outcome is never sourced from the request that asked for it. The same rule reaches a count of zero: layout-within-group’s ancestorsResized: 0 was true and undecodable, so that tool now also reports ancestorPropagation, a stable code saying which situation produced the number. The count cannot stand in for it in either direction: only propagated guarantees a count above zero, five codes always report zero, and two — stopped-at-non-native-ancestor and depth-cap-reached — arrive with either. Those two are the ones that leave a container above yours too small, so a positive count there reads as success and is not. A response field that reports an outcome is also omitted where nothing has run: a bulk-mutate queued into a batch or parked awaiting approval reports no allSucceeded verdict, because the operations it describes can still decline at commit.

In batch and approval modes nothing is effective by construction, so the entity is nested under preview beside a batch or proposal sibling naming the deferred state, and never appears at the top level of result where an agent would read it as state the model holds.

The rule is enforced, not merely intended: a contract test walks every registered tool and requires each to classify exactly once as read-only, covered by an oracle, or listed in a committed gap registry with a stated reason. A tool classified nowhere fails the build, and the registry’s entry count is a lower-only ceiling — so shipping a tool that cannot report effective state takes a deliberate, reviewable admission rather than silence.

Error Handling

Structured errors with actionable guidance:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Relationship type not valid between these elements",
    "details": "ServingRelationship requires ApplicationComponent as source",
    "suggestedCorrection": "Use an ApplicationComponent or change relationship type",
    "archiMateReference": "ArchiMate 3.2 § 5.1.2"
  }
}

The same identifier is deliberately spelled differently across the surface — an element’s model id is id on update-element, elementId on add-to-view and delete-element, and objectId on move-to-folder — and no tool schema declares additionalProperties, so a key spelled a sibling tool’s way is dropped before the handler sees it. A missing-parameter error therefore names the near miss: it reports the spelling that was supplied alongside the one this tool requires, on the standalone read and on bulk-mutate’s per-operation read alike, so the caller is not told a parameter is missing while holding it under a name one synonym away. Inside bulk-mutate the same failure now carries its own correction rather than the generic “fix the failed operation and retry the entire call”, which on a 150-operation call is the least useful advice available.

When more than one entry fails, bulk-mutate and apply-positions return a failed array whose rows carry each entry’s own index, its errorCode, its message and its suggestedCorrection. Rows do not repeat what they share. A long ending common to every row of one error code is published once beside the array — in messages and corrections, keyed by that error code — and the row names it with messageRef or correctionRef. Nothing is truncated: a split row keeps its own head under the field’s own name, and head followed by the shared string is byte-for-byte what the row used to carry. A message is never taken away whole, because it is the row’s own account of what went wrong; a row that shares the whole of its suggestedCorrection carries correctionRef and no suggestedCorrection at all — absent rather than shortened, so a client that ignores the reference finds a gap rather than a fragment it would read as complete. Whether a key is present on a row depends only on that row’s own content, so rows stay independently parseable.

Mutation Pattern

All mutation tools use the PreparedMutation pattern:

1. Validate inputs and build the command (on Jetty thread)
2. Dispatch execution to UI thread via Display.syncExec()
3. Execute through Archi’s CommandStack (enables undo/redo)
4. Return result DTO

For connections, redo() must null-then-reconnect due to Archi’s connect() early-return guard.

Adding a New Tool

1. Create or extend a handler in handlers/
2. Register the tool in registerTools() — define the JSON schema, description, and call handler
3. Add model access if needed — new method on ArchiModelAccessor interface, implemented in ArchiModelAccessorImpl (returns DTOs, not EObjects)
4. Format responses using ResponseFormatter with the standard envelope
5. Handle errors — catch at the handler boundary, translate to structured ErrorResponse
6. Write tests — mock ArchiModelAccessor for handler tests (no EMF runtime needed)

Testing

The test bundle (net.vheerden.archi.mcp.tests) is an OSGi fragment with Fragment-Host: net.vheerden.archi.mcp, giving it full access to main plugin classes.

• Headless one-command run (recommended): tools/run-tests.sh compiles both projects from source against your local Archi/Eclipse install and runs the headless-safe majority of the suite (~95% of classes), asserting testsRun > 0 per class and emitting JUnit XML to build/test-results/. No Eclipse IDE, no hand-maintained class list — the run set is auto-discovered by scanning for *Test.java minus the exclusion manifest tools/osgi-excluded-tests.txt. See tools/README.md. Override locations with ARCHI_HOME / ECLIPSE_HOME / M2_REPO (so CI can reuse the same script). Use tools/run-tests.sh --swt for SWT/display-required classes.
• Run the OSGi-only bucket in Eclipse as a single “JUnit Plug-in Test” (the AllPluginTestsRunner launch) — the OSGi runtime it provides is required for the classes the headless harness excludes (listed in tools/osgi-excluded-tests.txt). Individual classes can also be run one at a time.
• Pure-Java tests (geometry, layout algorithms, routing) can also run as standard JUnit tests without the Eclipse runtime
• Handler tests mock ArchiModelAccessor — no Archi installation needed
• Tests requiring the Eclipse/OSGi runtime — three classes touch Archi/Eclipse runtime singletons that only initialise under OSGi, so they must be run as a JUnit Plug-in Test (a headless JVM cannot initialise them and they are guarded to skip there rather than fail):
  • McpPreferenceInitializerTest — org.eclipse.core.internal.preferences.ConfigurationPreferences
  • McpServerManagerTest — com.archimatetool.editor.model.IEditorModelManager
  • ArchiModelAccessorImplTest (the two specialization-relationship cases) — com.archimatetool.model.util.RelationshipsMatrix

Dependencies

Eclipse/Archi runtime dependencies: org.eclipse.ui, org.eclipse.core.runtime, org.eclipse.swt, org.eclipse.jface, org.eclipse.zest.layouts, com.archimatetool.model, com.archimatetool.editor.

PDE Build Notes

This is a pure Eclipse PDE project — no Maven or Gradle. Key files:

• MANIFEST.MF — OSGi bundle metadata, Bundle-ClassPath lists all JARs
• build.properties — PDE build includes
• .classpath — Eclipse project classpath

When adding a new JAR dependency, update three places: the lib/ directory, MANIFEST.MF Bundle-ClassPath, and .classpath.

Acknowledgments

• Archi - Archi® modelling toolkit
• ArchiMate - ArchiMate® Specification
• Eclipse IDE - Eclipse IDE™
• MCP — Model Context Protocol™
• ELK - Eclipse Layout Kernel™
• Jackson - Jackson JSON Library
• Jetty - Eclipse Jetty® - Web Container & Clients
• SLF4J - Simple Logging Facade for Java

License

This project is licensed under the MIT License. See LICENSE for details.