ea_repository

ea_repository is the tool for the repository as a whole rather than for what is inside it. It tells you which model is open and opens or creates one, reports whether a newer AI Power Tools version exists, takes and restores package baselines, moves packages in and out as XMI files, runs EA's own report templates, rolls elements up into portfolio counts, carries the older skills installer, and builds the reporting business layer that Power BI and other reporting tools read. It has 27 operations in five groups.

Group	Operations	Effect on the model
Project	`get_repository_info`, `open_project`, `close_project`, `open_model`, `launch_ea`, `create_model`, `check_for_updates`, `aggregate_portfolio`	`create_model` creates a new model file; the others do not change model content
Baselines	`create_baseline`, `list_baselines`, `compare_baseline`, `apply_baseline`	`create_baseline` stores a snapshot; `apply_baseline` overwrites package content
Import and export	`export_xmi`, `import_xmi`, `generate_report`	`import_xmi` adds content to a package
Skills (legacy)	`list_available_skills`, `install_skills`, `prune_legacy_skills`, `get_skill_update_diff`, `resolve_skill_conflict`	None. They write files in your Claude folder, never the model
Reporting business layer	`build_business_layer`, `check_business_layer`, `remove_business_layer`, `build_reporting_database`, `replay_reporting_database`, `start_reporting_refresh`, `get_reporting_refresh`	None in the model's content. On the direct-access path, `build_business_layer` adds views to the EA repository's own database, in a schema of their own, and `remove_business_layer` drops them

Conventions for this tool:

Most operations need an open model. Without a running EA they return ea_not_running; without an open model, ea_no_model_open. The exceptions are launch_ea, open_project, open_model, create_model, check_for_updates, the skills-installer operations, and the reporting operations that do not read EA: replay_reporting_database, remove_business_layer and get_reporting_refresh.
Package numbers and baseline identifiers come from list_root_packages, list_child_packages and find_packages_by_name (Packages) and from list_baselines.
Read-only mode refuses create_model, create_baseline, apply_baseline, import_xmi, build_business_layer and remove_business_layer, and refuses start_reporting_refresh for a profile that builds inside the EA repository's own database.

Project

These operations answer "which model am I working in?" and move between models. Run get_repository_info before anything writes, because writing to the wrong model is silent. aggregate_portfolio is the odd one out: it is a read-only roll-up that supports stakeholder views such as "Westbrook business applications by lifecycle".

Operation	What it does	When you would use it	Changes the model	Logic
`get_repository_info`	Reports the open model's location, EA version, repository type, whether EA user security is on and who is signed in, the root packages, and any update notice	Right after `ping`, to confirm the intended model is open before writing	No	Deterministic
`open_project`	Opens a model file in the running EA. If that model is already open nothing happens; if another is open, EA switches	Switching to the intended model at the start of a session	No	Deterministic
`close_project`	Closes the open model without exiting EA	Releasing a model file before another tool needs it	No	Deterministic
`open_model`	Opens an existing model file by path, always issuing the open	Recovering from "no model open"; opening a model by path	No	Deterministic
`launch_ea`	Starts EA on this machine and waits up to 30 seconds for it to respond	When EA is not running, after you have agreed. With computer use the assistant can instead start EA through the desktop	No	Deterministic
`create_model`	Creates a new, empty local model file (`.qea`) and opens it	Starting from an empty model, or a scratch model	Yes: creates a new file	Deterministic
`check_for_updates`	Reports whether a newer AI Power Tools version exists, with download and release-notes links, how AI Power Tools was installed on this machine, and the upgrade steps for that installation	Answering "am I current?" and "how do I upgrade?"	No	Deterministic
`aggregate_portfolio`	Groups every element of one stereotype by the value of one tagged value and returns the groups with counts, largest first	Portfolio roll-ups, for example Westbrook `WBABusinessApplication` elements grouped by lifecycle	No	Deterministic

Notes: project operations

get_repository_info shows phantom roots. EA's in-memory list can include a root package that no longer exists. Such a root is flagged as unresolved and is not counted. Do not use it for anything. Update notices come from background checks that refresh at most once every 24 hours and never delay the reply.
Opening a file is slow. EA may show "(Not Responding)" for several seconds. Wait and check again before repeating the request. The server attaches to one EA instance and does not start a second one against the same file. If EA refuses to open a file, the failure arrives as a plain tool error and not as a named one, and EA often shows a dialog as well. See Blocking dialogs in How tools and operations work for how the dialog is read and dismissed.
Launching EA is your decision. The server returns launch_ea as a remedy and never launches by itself; the skills ask first. With computer use the assistant can start EA through the desktop instead, and open the model through EA's own menus. Without computer use, launch_ea still starts EA, or you start it. Either way, check that EA is not already running before you agree. Starting a second instance against the same model file can damage work, and a per-user EA license limits how many instances can run at once.
create_model always makes a .qea file. A name that does not end in .qea gets the suffix appended. It is reported to fail on some EA builds. If it does, the assistant creates the model through EA's own menus when it has computer use and then calls open_model. Without computer use, it asks you to create the model in EA and give it the path. Read-only mode refuses create_model.
check_for_updates is advisory. It reads the public releases feed in the background and sends no model information. The notice names how the server was installed, worked out from where the server runs, and gives the upgrade steps for that installation (Updating and uninstalling):
- the Claude Desktop extension (the server sits in Claude Desktop's Claude Extensions folder): download the newer extension file and drag it onto the Extensions pane, disabling the extension before you click Update and re-enabling it afterward. Only this installation carries the extra warning about disabling first, because the running server otherwise holds a lock on its own file;
- the VS Code extension: download the newer extension file from the release page, install it from the Command Palette and reload the window;
- a server that arrived inside a plugin package (in Claude's plugin cache or Claude Desktop's plugin staging folders): the notice says the plugin carries only the skills, gives the steps to install the Claude Desktop extension, and says to sync novocircle under Manage marketplaces and restart Claude Desktop for the skills. For a plugin file uploaded in Claude Desktop, which does not update itself, it sends you to the skills release for the newer file;
- a location it does not recognize: neutral guidance to download the release and install it the way you installed this one, then restart the application that runs the server. The skills are checked through ping and not through this operation (The AI Power Tools MCP Server for Sparx EA).

Baselines

A baseline is EA's own snapshot of one package and everything beneath it, stored inside the repository. Take one before a bulk edit, a package delete, an MDG rollout, an XMI import or a ruleset fix. The four operations wrap EA's baseline feature, and the workflow around them (when to offer a baseline, how to review the ones that accumulate) is in the ea-change-management skill.

Operation	What it does	When you would use it	Changes the model	Logic
`create_baseline`	Takes a baseline of a package and its subtree, under a version label and optional note, and returns the new baseline's identifier	Before any change you cannot afford to lose	Yes: adds a snapshot to the repository	Deterministic
`list_baselines`	Lists the baselines stored against one package	Finding the baseline to compare or restore; re-confirming the target just before an apply	No	Deterministic
`compare_baseline`	Compares the package as it is now with one of its baselines and returns an item-by-item, property-by-property difference	Seeing what changed since a snapshot; previewing what an apply would undo	No (it opens EA's own comparison view)	Deterministic
`apply_baseline`	Restores a package and its subtree to a baseline, then checks by comparing again that nothing differs	Rolling back a failed bulk edit, delete or import	Yes: destructive. Overwrites package content	Deterministic

Notes: baseline operations

create_baseline finds its own result by label. After EA creates the baseline, the server looks it up by version label and note and takes the first match, so reusing a label can return an older baseline's identifier. Use a distinct label each time and confirm with list_baselines.
A baseline is always the whole subtree. Each baseline adds a compressed copy to the repository file, which grows a .qea file, so baseline the narrowest package that contains the change.
list_baselines is reliable for version and notes only. In some EA builds the date and author come back empty, so do not build checks on them. A baseline is deleted with a direct database statement or in EA's user interface.
Reading a comparison. Each compared item has one of four statuses: Model only (in the model, not in the baseline, so added since), Baseline only (deleted since), Changed, or Identical. Identical items are counted but not listed unless asked for. The reply also gives live counts for the whole current subtree. Connector counts include only connectors whose source element is inside the package.
The two identifier spellings are not interchangeable. Items carry the braced GUID that element lookups take; the compared packages carry EA's underscore form. The server never merges them and does not warn if you mix them; the result is simply no match.
If a comparison seems to hang, EA is probably showing a dialog. EA reports an unrunnable query as a dialog that holds the connection until someone dismisses it, and the server cannot see it. See Blocking dialogs in How tools and operations work: with computer use the assistant reads and dismisses it, and without computer use you paste a screenshot of it into the conversation and then dismiss it.
apply_baseline verifies instead of trusting. After driving EA's restore, the server compares again and reports "restored" only if EA finds no remaining differences. Possible outcomes are restored; already identical (nothing changed); EA accepted the restore but nothing changed, with the manual route (right-click the package, Package Control, Baselines, select the baseline, Restore), which the assistant follows in EA's window when it has computer use and otherwise hands to you; and several named failures. Every reply carries the warning that the operation overwrites current content. If the comparison run after the restore itself fails, a missing comparison reads as "no differences", so a reply can say "restored" without the check having run. Run compare_baseline yourself afterward when the outcome matters.
Read-only mode refuses create_baseline and apply_baseline.

Import and export

These operations move a package out of the model as an XMI file, bring one in, or produce a formatted document from a package. The ea-import-export skill drives them.

Operation	What it does	When you would use it	Changes the model	Logic
`export_xmi`	Exports a package as an XMI file, then reads the file back and refuses to report success unless it is XMI and contains the package's content	Moving a package to another repository or tool; making a file copy of a package	No (writes a file)	Deterministic
`import_xmi`	Imports an XMI file into a package and reports how many items arrived	Bringing a package from another repository or tool; restoring an exported package	Yes: adds content to the target package	Deterministic
`generate_report`	Runs one of EA's report templates against a package and writes the document	A formatted document (headings, tagged values, prose) rather than a picture	No (writes a file)	Deterministic

Notes: import and export operations

Export is checked, not trusted. The server rejects a file that is not XMI or that holds none of the package's element names, and it names the failure. The check confirms the export is not empty; it does not prove the export is complete. Six XMI versions are accepted: 1.0, 1.1, 1.2, 2.1 (the default), 2.4.1 and 2.5.1.
Export is not a rollback. For a rollback point inside the same model, take a baseline (Baselines).
Import changes the target in place. Take a baseline of the target first. It brings diagrams across by default and gives everything imported fresh GUIDs, so the import behaves as a copy. Leave the fresh-GUID setting on unless you are restoring into a repository that does not already contain these GUIDs: importing with the original GUIDs into a model that already holds them can leave the call running without ever returning. A result of zero items is reported as a failed import, never as a success. The count covers elements and child packages directly under the target.
Reports are produced by EA's own report engine. They are reported to come out as RTF only, so name the output file with an .rtf ending. The template name is not validated: a name that matches nothing can still produce EA's default document and report success, so open the output and check that your template was used. Never pass an empty template name, which can hang the call. Report templates are authored in EA's own menus. With computer use the assistant can drive that editor (the ea-help skill covers the procedure). Without it, you author the template in EA, and the assistant then runs it with generate_report.
Check a report before sharing it. The document embeds each element's author and last-modified-by values exactly as the model holds them, which are the modelers' EA or Windows user names.

Skills (legacy)

The AI Power Tools skills reach your machine through the Claude plugin, which carries the skills and no server (Claude plugin). These five operations are an older installer that fetched the skills from a public repository and copied them into %USERPROFILE%\.claude\skills. They remain for machines that still use that older channel and for cleaning it up. They never touch the model; they read and write files in your Claude folder and contact the public skills repository.

Operation	What it does	When you would use it	Changes the model	Logic
`list_available_skills`	Lists the skills in the public bundle and whether each works with the running server	Checking what the older installer would install	No	Deterministic
`install_skills`	Installs skills (and rulesets) from the public bundle. It declines when the plugin already supplies the skills	Only on machines that deliberately use the older channel	No (writes files)	Deterministic
`prune_legacy_skills`	Removes skill folders AI Power Tools installed earlier and has since renamed, withdrawn or relocated. A dry run unless told to apply	Clearing leftovers of the older installer	No (deletes files when applied)	Deterministic
`get_skill_update_diff`	Returns the local and the latest published content of one skill file that has a conflict	Reading both versions before resolving a conflict	No	Deterministic
`resolve_skill_conflict`	Applies your decision (keep local, use the published version, or use a merged text) to one locally edited skill file	Finishing a conflict resolution on the older copy	No (writes a file)	Deterministic

Notes: skills (legacy) operations

Plugin plus older copy loads every skill twice. The skills then appear unprefixed and again as ai-power-tools:<name>, which doubles their cost in the assistant's context. The supported cleanup is the migration script migrate-to-plugin.ps1, described in Moving from an older installation; run it with its what-if option first. It removes only the copies the older installer's own record proves it wrote, and it reads both forms of that record, so it also finds installs made before version 2.2.0, whose record sits inside the skills folder. prune_legacy_skills does not by itself resolve the doubling, because it never removes current skill folders.
With the plugin found installed, the skills check reports leftovers only. When the server finds the plugin installed (it runs from the plugin cache, or Claude's plugin register lists the plugin), the background skills check does not fetch the release manifest. The only thing it reports, in the skills-update block of get_repository_info, is skill copies the older installer left in %USERPROFILE%\.claude\skills, which load a second time beside the plugin's, with migrate-to-plugin.ps1 as the remedy. With no leftovers, it reports nothing. A plugin installed on a claude.ai account is kept in a store the server cannot read. When the server is the Claude Desktop extension, the skills come from that plugin, so the block never recommends install_skills. It lists the older installer's copies, if any (they load a second time beside the plugin's skills in the Code tab only), and says to add the plugin on your claude.ai account if it is not there yet and then to remove the copies with migrate-to-plugin.ps1 or prune_legacy_skills applied with plugin_confirmed, which on the extension needs only your confirmation. With no copies, it says nothing once the assistant's ping has reported a skills release, and otherwise gives one pointer to claude.ai/customize/plugins, where you add the NovoCircle/ai-power-tools-skills marketplace and install AI Power Tools. On any other route, when the assistant's ping reports a skills release that no copy in the skills folders can have produced, the block lists the older installer's copies with a conditional note that they duplicate the plugin's skills if you installed the plugin on your account.
install_skills declines when the plugin supplies the skills. Nothing is written, and the reply says to sync the novocircle marketplace at claude.ai/customize/plugins and then quit and reopen Claude Desktop. A force option installs anyway, and also overwrites files that look locally edited. Read whether the install is complete, not whether the call succeeded: the call can succeed while a requested file is not in place. Each downloaded file is checked against a published fingerprint, and a file that does not match is not written. It refuses entirely if the server is older than the bundle requires.
A "locally edited" file is a suspicion, not a finding. A file counts as edited only when it differs from both the bundle and the installer's own record of what it installed. Show the list, then choose between the force option and the diff-and-resolve route.
prune_legacy_skills removes only what it can prove AI Power Tools installed. A folder goes only if the install record lists it and the plugin is found installed, or its exact name is one AI Power Tools shipped before, with no prefix matching. When the plugin is only reported by the session's ping, it lists the record's copies and removes them only when called with apply and plugin_confirmed, which is set only after you say you installed the plugin on your claude.ai account. Without it the reply carries a confirmation-needed message and the copies stay. A skill you wrote yourself is never touched, even if its name starts with ea-. Edited files are backed up first. Skills in the old location %APPDATA%\Claude\skills, which no Claude client reads, are also cleared.
All four target names mean the same place. auto, desktop, vscode and cli all resolve to %USERPROFILE%\.claude\skills, the only folder Claude reads skills from. Backups of overwritten files go to a timestamped backup folder inside it.
Rulesets travel the same way. The ArchiMate 3.1 ruleset is installed with the older installer's other content; see ArchiMate 3.1 ruleset and ea_validate.
Read-only mode does not refuse these operations, because they write files on disk and not the model.

Reporting business layer

These seven operations build the business layer: reporting tables named and shaped by the modeling language that governs your model, which Power BI, a SQL client or an agent reads instead of EA's own tables. They read the technology's definition the same way get_mdg_from_runtime does (Discovering technologies), read the repository, and write SQL Server views, a separate reporting database, or files. They never write an EA table and never change the model's content. The ea-reporting-database skill drives them, including the decisions they need from you, and ea-power-bi builds the Power BI project from the result.

The business tables. Every build produces the same tables, whichever way it is delivered, so a report built on one delivery works on another:

entity tables, one per element stereotype the technology declares, named by the stereotype's alias, with the declared tagged values as typed columns and each element's package path;
connector tables, one per combination of source stereotype, connector stereotype and target stereotype the technology allows, with the connector's tagged values as columns;
tables marked (not in MDG) for stereotypes and connector combinations outside the technology that you chose to include;
tag-row tables, only where a column cannot hold the data: tagged values the technology does not declare, and tagged values that list several referenced elements;
a Table Directory, one row per business table.

Every build also writes a definition file beside the profile, listing every table with its columns, types and row counts. The Power BI generator reads it, so it needs no database connection.

The reporting profile. Every operation except get_reporting_refresh, which takes the run id returned by start_reporting_refresh, takes the path of a saved reporting profile, a file you keep. It records the technology, the packages in scope and the packages left out (by GUID, so a renamed or moved package keeps its setting), what to include beyond the technology, and where the business tables go. Every build and refresh reuses it, so the answers you gave once are not asked again. The skill writes the profile with you.

Three ways to deliver the tables. The profile names one of them.

Delivery	For whom	What is built	Data
Views in the EA repository's own database	You can reach the EA database, it is SQL Server, and the account may create views in it	The business tables as views in a schema of their own inside the EA database, plus views of EA's own tables limited to the packages in scope	Live: the views read EA's tables as they stand
A reporting database	You have no direct database access, for example through a cloud connection, but you can run SQL Server or have a SQL database in Microsoft Fabric	A separate database, on SQL Server or a SQL database in Microsoft Fabric, holding a copy of EA's tables, read through EA, with the excluded packages cut out, and the business views over that copy	A snapshot, rebuilt in full on every build
Parquet files	You have no direct database access and no database to run	The business tables' rows, written beside the profile for the Parquet step in ea-power-bi, which writes the files	A snapshot, rewritten on every build

SQL Server is reached through the database providers Windows already has, with the Windows account that runs AI Power Tools, so nothing extra is installed. A reporting database in a SQL database in Microsoft Fabric is reached with Microsoft Entra sign-in instead, when the profile asks for it: the first operation in a server process that opens the database shows Microsoft's sign-in window, a person signs in with a Microsoft work account, and later operations in the same process reuse the sign-in. It needs the Microsoft OLE DB Driver for SQL Server, and the database is created in the Fabric portal first. Views in the EA repository's own database use Windows authentication only. See ea-reporting-database.

Operation	What it does	When you would use it	Changes the model	Logic
`build_business_layer`	Builds the business tables as SQL Server views from a profile, all inside one transaction in their own schema, and writes the definition. For direct access it first checks that the database holds an EA repository and that the account has the rights it needs, and changes nothing if either check fails	Building the business layer with direct access; regenerating the views after the technology or your inclusion choice changed	No. Writes views into the target database, which with direct access is the EA repository's own database	Deterministic
`check_business_layer`	Checks a built business layer without changing it: whether it aligns with the technology's metamodel and, by default, whether every value matches an independent read through EA	Acceptance check after a build; before quoting a figure from the layer	No	Deterministic
`remove_business_layer`	Drops every view in the profile's schema, then the schema. EA's tables, and a reporting database's copied tables, are not touched	Removing everything AI Power Tools placed in the EA database; starting over	No. Drops the views	Deterministic
`build_reporting_database`	Reads EA's tables through EA, cuts the packages the profile leaves out, and reports a preflight. Unless you asked for the preflight only, or the preflight found a blocking defect, it loads the reporting database and builds the business views over it, or writes the rows for Parquet. Keeps this run's extract beside the profile	Building or rebuilding a reporting database or Parquet output; running the preflight on its own	No. Writes a separate database or files	Deterministic
`replay_reporting_database`	Rebuilds the reporting database, or the Parquet rows, from the last kept extract, with no EA connection	Retesting a build; settling a disputed figure against the exact rows it was built from	No	Deterministic
`start_reporting_refresh`	Starts a refresh of a saved profile in the background and returns at once with a run id. For views in the EA repository's own database it regenerates the views; for a reporting database it runs the full build; for Parquet it rewrites the rows	A refresh triggered by a scheduled agent, or any build you do not want to wait on	No. As for the build it runs	Deterministic
`get_reporting_refresh`	Reports a refresh's status (running, succeeded or failed) and, once it has finished, its full result or why it stopped	Polling a refresh started with `start_reporting_refresh`	No	Deterministic

Notes: reporting business layer operations

What they need. EA running with the repository open on this machine, for every operation except replay_reporting_database, remove_business_layer and get_reporting_refresh. A build reads the technology's definition from a registered file or the model (Technology states), and a repository with no technology has no metamodel to build from. SQL Server is the only database for direct access. A reporting database is on SQL Server or in a SQL database in Microsoft Fabric.
The preflight comes first. Before loading anything, build_reporting_database reports the rows read and the rows it would keep, the links that cross from kept content into a package left out (kept, with an "(excluded)" stand-in at the far end that shows the element type, never the name), and two kinds of finding. A blocking finding stops the build: a connector whose stereotype is stored as text with no binding to the technology. Fix it in EA, after a baseline, and run the preflight again. A flag is shown and the decision is yours: an element carrying two of the technology's stereotypes (it appears in both tables), a root package created since the profile was saved (left out until you add it), a profile entry that matches no package, and an element with two tagged values of the same name. Asking for the preflight only writes nothing; a blocked preflight writes nothing either.
Readers never see a partial build. The views are rebuilt inside one transaction, and a reporting database is built in a staging area and swapped in inside one transaction. A build or refresh that fails, or is stopped by its preflight, leaves the previous reporting data in place.
It never replaces an EA repository. A reporting-database build refuses a target database that holds an EA repository's own tables, because a build replaces the tables in its target. A direct-access build refuses a database that holds no EA repository.
The kept extract. For a reporting database and for Parquet, the rows actually loaded, after the cut, are kept beside the profile, replacing the previous run's; only the last run is kept. Content in excluded packages is never written to disk. The kept extract holds everything you chose to report, so treat it with the same care as the reporting data. Direct access reads EA live and keeps no extract.
Checking the build. check_business_layer reports alignment with the metamodel: every allowed combination has a table, every connector lands in an allowed combination or is reported as outside every one, and every included element is in at least one entity table. With values on, it compares the names, package paths, tagged-value columns, connector ends and connector tagged values in the views with a separate read through EA, so the open repository must be the one the layer was built from. A check that compared nothing is a failure, never a pass. A Parquet build has no views to check; its build reports the same alignment summary.
Builds flag drift. Every build and refresh reports stereotypes and connector combinations that the saved inclusion choice does not cover, and a technology whose version has changed since the choice was made. A refresh uses the saved choice and does not decide anything new; you review the flags and update the profile.
Values as EA shows them. Of two tagged values with one name on an element, the first is used, as EA's Properties window shows it. A memo tagged value is read from its notes. A tagged value that lists referenced elements becomes a tag-row table with one row per element. Dates read through EA in the machine's locale are stored in one standard date form. An empty value and a missing value cannot be told apart, because EA returns both the same way.
The refresh. One refresh of a profile runs at a time; asking to start another while one runs returns the running one's id. Run ids are kept until the server restarts. To keep the data fresh, a scheduled AI agent connected to the machine where EA runs calls start_reporting_refresh and polls get_reporting_refresh. EA must be running with the repository open on that machine, or the refresh fails. A refresh into a SQL database in Microsoft Fabric also needs a person to complete the sign-in when the server process first opens the database; an unanswered sign-in stops the run after about ten minutes and leaves the previous data in place.
Read-only mode refuses build_business_layer and remove_business_layer, and refuses start_reporting_refresh for a direct-access profile, because those write into the EA repository's database. It does not refuse build_reporting_database or replay_reporting_database, which write a separate database or files.
No masking. Everything in a package in scope is reported, including notes and tagged values. To keep content out, leave its package out.