MCP server: tools and operations

The AI Power Tools MCP Server for Sparx EA is the part of AI Power Tools that touches Enterprise Architect (EA). It attaches to a running EA, reads and changes the open model on request, and hands the answer back to the AI assistant. The server contains no AI. Every operation in this part is Deterministic: given the same request and the same model state, it gives the same result, and no AI judgment is involved (Where the AI decides and where AI Power Tools decides). The model state is part of the input, so the same request on a model that has since changed can return a different answer, and that is still deterministic. Where an operation reports a finding, such as an element with no connectors, deciding what the finding means is left to the assistant or to you.

The server offers six tools and one stand-alone health check. Each tool groups a family of related operations.

That is 149 operations. Section Inside the server describes the shared modules inside the server.

How tools and operations work

This section describes behavior shared by every operation, so the entries that follow do not repeat it.

Tools and operations

A tool is a named capability the assistant can call, such as ea_model. An operation is one specific action inside a tool, such as create_element or find_orphan_elements. Every call names a tool, names an operation, and supplies the inputs that operation needs.

You do not make these calls yourself. You describe what you want in plain language, and the assistant chooses the tool and operation and supplies the inputs. When a skill is active (How skills work), the skill tells the assistant which operations to use and in what order. The assistant also reads the answer back to you and explains it.

The server groups 149 operations behind six tools instead of publishing 149 separate tools. This keeps the assistant's working context small, so it has more room for your model and your instructions.

The server and the assistant's other capabilities

Operations are what the server does, and the server's limits are not the limits of AI Power Tools as a whole. Where this part says the server does not do something, such as start EA, dismiss a dialog or draw a diagram on screen, read it as a fact about the server. It is not a statement about what the assistant can do for you. The assistant has other capabilities, and which of them are available depends on your client (Capabilities and surfaces).

• Computer use. The assistant sees and operates desktop applications, so it also works in EA's own window. It starts EA and opens a model. It reads and dismisses EA's blocking dialogs, which EA raises instead of returning an error (Blocking dialogs). It looks at the real diagram in EA, not only the picture the server renders. It also does the tasks that exist only in EA's interface, such as Manage Technologies and report templates. Without computer use, the assistant tells you which of these steps are yours and asks what you see.
• Local code execution. The assistant runs the code engines that ship with the skills, on the machine where EA runs (Part 4, Code engines). The engines compute fixed answers, such as diagram geometry and reporting extracts, and they do not use the server's operations to do it. Where local code execution is not available, an engine-dependent step cannot run, or the assistant works the answer out itself at a higher token cost and with less consistent results.

Each skill in How skills work states which capabilities it uses and what happens without them.

Blocking dialogs

Enterprise Architect reports many failures as a modal dialog that waits for a person and blocks every later call. The server cannot see the dialog, so a call that appears to hang is usually this. The same story applies wherever a dialog comes up in this reference:

• With computer use: the assistant sees the dialog in EA's window, reads it, uses the message to correct the call, dismisses the dialog, and keeps going.
• Without computer use: you take a screenshot of the dialog and paste it into the conversation so the assistant can analyze it. Then you dismiss the dialog so processing can continue.

Repository connections

Enterprise Architect opens a repository as a local file (.qea or .qeax), as a server connection (EA connects directly to a shared repository held in a database), or as a cloud connection (EA connects to a shared repository through Pro Cloud Server, middleware that lets EA reach the repository database over HTTPS; it does not necessarily run in the cloud). For AI Power Tools a cloud connection behaves the same as a server connection: EA opens the connection, and the server attaches to EA either way. Where an operation needs a local file, for example adding images to the model's image library, its entry says so.

What you see in the transcript

Each call appears in the conversation as a tool-call entry that shows the tool name, the operation name and the inputs, followed by the result. Depending on your client, the entry may carry a prefix that names the server, may be collapsed until you expand it, and may ask you to approve the call before it runs. These entries are the audit trail of what the assistant did. Operation names in this reference are in code font because that is how you will see them.

Reading a transcript, look for three things:

• Which operations ran. An operation whose name starts with create_, update_, delete_, set_, add_, move_, duplicate_, apply_ or import_ changes something in the model. Names that start with build_, replay_, remove_ or start_ build, rebuild or drop reporting data outside the model (Reporting business layer). Names that start with get_, list_, find_, summarize_, check_ or verify_ only read.
• What the inputs were. The identifiers and names the assistant used show what it believed it was acting on.
• What came back. Success, a named error, or an answer that is empty or smaller than you expected.

How errors are reported

A failure comes back as a short machine-readable error name together with a plain-language message. The assistant reads the name, not you; it usually corrects the call and tries again, so you often see an error followed by a retry. The families you may meet:

Five points matter when you read results:

• A failure is not always named. A few failures reach the assistant as a plain tool error with no error name, for example when EA cannot open a file, or when an operation that needs an identifier receives none. A reply with an error name or a success flag of false is a failure; so is a tool error.
• An unreadable query result is a failure, not an empty answer. Many operations read the model through EA's query interface. When EA hands back a result the server cannot read, including one larger than the 64 MB limit the server applies to XML, the call fails with an error instead of reporting "nothing found" or a count of zero. A blank reply from EA is still read as no rows, and EA also gives a blank reply for some queries it could not run, so an empty answer that surprises you is worth a cross-check. Query results also cannot tell an empty value from a missing one: EA returns both the same way.
• Some reads answer "empty" instead of "not found". Operations that look things up with a query, such as the multi-store tag readers, the filtered connector lookup, and the orphan and composite audits given a package that does not exist, return an empty result and not an error. If an empty answer surprises you, ask the assistant to confirm the identifier with get_element, get_package or get_connector.
• A list-returning operation can return an error instead. Asking for the children of a package that does not exist returns a not-found error, not an empty list.
• Success can be partial. The next subsection explains this.

"ok" is not proof: verify

A successful reply means the operation ran. It does not mean everything you asked for happened.

• Some properties are rejected while the call still succeeds. The create and update operations report which properties were applied and which were rejected. A misspelled property or a tag name passed as a property is rejected, and the call still succeeds. Compare what was applied with what you asked for.
• EA can refuse a write without saying so loudly. Some operations check whether EA accepted the write and report a named rejection. Others do not, and report success regardless. Applying a stereotype to an element whose base type does not match is one case that EA may refuse silently; the reply carries a warning when the value does not read back.
• Bulk results say "created", not "complete". See the bulk subsection below.
• EA's open window can be stale. A change written directly to the database shows in EA only after the diagram or browser is reloaded.

So verify what matters. Ask the assistant to read the object back with the matching get_ or list_ operation, to count the result with a summary, or to render a diagram with verify_diagram and show you the picture. With computer use, the assistant can also look at the diagram in EA's own window. The skills in How skills work build this check into their steps. When you review a transcript, a write followed by a read-back is the pattern you want to see.

Identifiers

Every package, element, connector and diagram has two identifiers.

• The number EA assigns. It is specific to one model: element 301 in your development model is a different object, or nothing, in another model. Do not carry numbers between models.
• The GUID (the braced identifier). It survives export, import and copy as EA stores it, so it is the one to quote across models.

Operations that get, update or delete a package, element, connector or diagram accept either. If you supply both, the number is used. You rarely type either one: you give names and locations ("the Customer Portal element in the Westbrook application catalog"), and the assistant looks the identifiers up with the find_ and list_ operations, then quotes them in the transcript.

Two places where identifiers are not uniform:

• Class members. An attribute or operation is updated by its GUID but deleted by the owning element's number plus its own number. Parameters of an operation have no identifier of their own. The assistant handles this; it matters only if you read the raw calls. See Class members.
• Baselines. A baseline comparison reports packages in one GUID spelling and items in another. They are not interchangeable, and passing one where the other is expected matches nothing without an error. See Baselines.

Bulk operations

Operations whose names end in _bulk take a list of items and apply each one independently. One item failing does not stop the others, and the reply reports one outcome per item: created, skipped as already present, or failed with a reason.

The create operations are idempotent. An element is skipped when one with the same name, package and stereotype already exists; a connector is skipped when one with the same source, target, type, stereotype and name already exists. Running the same load twice is therefore safe, but it also means a skipped item does not update the existing object. Bulk operations save a great deal of time on catalog loads. After a load that depends on tagged values or connector stereotypes, verify them, because the per-item outcome does not always list what failed to apply.

Some operations also accept verbose. By default they return a minimal record (identifier, GUID, name), which is the right choice in a loop; verbose returns the full description of the object.

Destructive operations

EA has no undo for changes made through this server. Every write takes effect immediately, and a delete is permanent. The server does not ask "are you sure". The skills ask you; if you instruct the assistant directly, state the scope you mean.

apply_baseline deserves its own warning. It overwrites the current content of a package and everything beneath it with the stored snapshot. Anything added since the baseline is removed, anything deleted since is restored, and every edit made by anyone is reverted. It cannot be undone and has no confirmation step. Before you approve it:

1. take a fresh baseline of the package as it stands now;
2. confirm the package and the baseline are the ones you intend, using list_baselines and get_repository_info;
3. preview the effect with compare_baseline;
4. never apply a baseline that was not taken for this purpose.

Two further operations change the target in place and are worth protecting with a baseline: import_xmi (it adds content to a package) and duplicate_package (it adds a copy into a package that may already hold content). A direct write through the query operations in ea_analyze is also permanent and bypasses EA's own checks. The safety net is a baseline taken before the change, with the ea-change-management skill. Do not copy the model file as a substitute; a baseline is the supported way back.

Read-only mode

Turn on Read-only mode on the Claude Desktop extension's Configure screen (off by default). The server then refuses operations that modify the repository and reports readonly_mode. The setting reaches the server as the environment variable EA_MCP_READONLY; the VS Code extension offers no such setting. The decision is made by operation name, plus a list of operations that change diagrams without a telling name:

• refused: any operation whose name begins create_, update_, delete_, set_, add_, move_, duplicate_, apply_, import_, install_ or write_, plus layout_diagram, remove_element_from_diagram, clear_element_image, build_business_layer and remove_business_layer. That includes create_model and create_baseline. start_reporting_refresh is refused when its profile builds the business layer inside the EA repository's own database;
• allowed, but forced to read only: the direct query operation, which then rejects any statement that would write;
• not refused: the skills-installer operations in Skills (legacy), because they write files on disk and not the model; build_reporting_database and replay_reporting_database, because they write a separate reporting database or files, not the repository (Reporting business layer); and select_element_in_browser, which changes only what EA highlights.

The diagram operations neaten_diagram_objects, resize_diagram_objects, collapse_parallel_connectors (including a preview run) and expand_parallel_connectors (ea_diagram) are refused too. So are create_diagram_description and update_diagram_description, previews included; audit_diagram_descriptions is allowed (Diagram descriptions). Read-only mode is a safety net, not a substitute for a baseline: use a baseline for anything you cannot afford to lose.

ping

ping is the health check. It confirms that the server process is running and reports the server's name and version, which for this release is 3.6.4. It is a stand-alone tool, not one of the operation groups: it takes no operation name and one optional input, the release of the skills in the session, and it does not contact EA. It therefore succeeds when EA is closed. The ea-start-here preflight passes the skills' release, so ping can say whether the server or the skills are behind the current release.

Notes: ping

• ping proves the server is up, not that EA is reachable or that a model is open. Follow it with get_repository_info (Project).
• It has no failure reply. If the server is not running, your client reports the tool as unavailable, and nothing else in this part can be called.
• AI Power Tools needs no activation or license check, so ping reports none.
• The skill ea-start-here calls ping first in its session check.