{
  "markdown": "# Enterprise Architect MCP Server\n\n[![npm version](https://img.shields.io/npm/v/enterprise-architect-mcp.svg)](https://www.npmjs.com/package/enterprise-architect-mcp)\n[![Node.js](https://img.shields.io/node/v/enterprise-architect-mcp.svg)](https://nodejs.org)\n[![License: EUPL-1.2](https://img.shields.io/badge/license-EUPL--1.2-blue.svg)](LICENSE)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522enterprise-architect%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522enterprise-architect-mcp%2522%255D%257D)\n[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_server-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522enterprise-architect%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522enterprise-architect-mcp%2522%255D%257D)\n\nA read-only [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for Sparx Enterprise Architect `.qea` exports. Gives AI agents access to EA analysis models — search elements, navigate packages, read use case scenarios, and traverse connectors — without a running EA instance.\n\nWorks with any MCP client (VS Code / GitHub Copilot, Claude Desktop, Cursor, Windsurf). Reads the `.qea` SQLite export directly, never writes to it, and every response carries completeness metadata so an agent can tell a truncated answer from a complete one.\n\n**Keywords:** MCP server · Sparx Enterprise Architect · `.qea` · UML · use case scenarios · package tree · connectors · diagrams · model search · AI agent tooling\n\n## Prerequisites\n\n- **Node.js 22+** (uses the built-in `node:sqlite` module)\n- A `.qea` file exported from Sparx Enterprise Architect\n\n## Installation\n\n### VS Code / GitHub Copilot\n\nThe quickest route is the **Install in VS Code** badge at the top of this page. There is nothing to\nfill in: the server asks for your `.qea` path the first time an agent queries the model, and\nremembers the answer for next time.\n\nTo register it from a terminal instead, which is handier for scripting or a shared setup, use one\nCLI call:\n\n```powershell\ncode --add-mcp '{\\\"name\\\":\\\"enterprise-architect\\\",\\\"command\\\":\\\"npx\\\",\\\"args\\\":[\\\"-y\\\",\\\"enterprise-architect-mcp\\\"]}'\n```\n\nThe `\\\"` sequences are for the `code` shim, which re-parses the argument after PowerShell has\nalready handed it over — escaping with PowerShell's own backtick, or using `--%`, still arrives with\nthe quotes stripped. The single quotes stop PowerShell from touching the string. On bash or zsh the\nplain form works instead:\n\n```bash\ncode --add-mcp '{\"name\":\"enterprise-architect\",\"command\":\"npx\",\"args\":[\"-y\",\"enterprise-architect-mcp\"]}'\n```\n\nTo configure it by hand instead, add to your project's `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"enterprise-architect\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"enterprise-architect-mcp\"]\n    }\n  }\n}\n```\n\nNothing personal is in that file, so it can be committed as-is and each developer answers the prompt\nonce on their own machine. If you would rather not be asked at all, name the path up front — as a\ntrailing argument, in an `env` block, or in a gitignored `.env` in your workspace root:\n\n```ini\nEA_QEA_PATH=C:\\EA\\exports\\model.qea\n```\n\n### Claude Desktop\n\nThe same path-less configuration goes in `claude_desktop_config.json` (`%APPDATA%\\Claude\\` on\nWindows, `~/Library/Application Support/Claude/` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"enterprise-architect\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"enterprise-architect-mcp\"]\n    }\n  }\n}\n```\n\nClaude Desktop does not run the server from a workspace folder, so a `.env` there is not reliable.\nIf the client cannot show the path prompt at all, the server says so instead of failing silently, and\nyou can name the path in an `env` block:\n\n```json\n\"env\": { \"EA_QEA_PATH\": \"C:\\\\EA\\\\exports\\\\model.qea\" }\n```\n\nTo run straight from source instead of npm, use `\"args\": [\"-y\", \"github:mm6502/enterprise-architect-mcp\"]`.\n\n## Configuration\n\nThe server does not need a path to start. It looks for one when an agent first queries the model, and\ntakes the first source that actually opens:\n\n1. **CLI argument** — `mcp-server-ea C:\\path\\to\\model.qea`\n2. **Environment variable** — `EA_QEA_PATH` (set in an `env` block or system env)\n3. **`.env` file** — `EA_QEA_PATH=...` in a `.env` file in the working directory\n4. **A remembered answer** — whatever you last told the prompt\n5. **The prompt** — the client asks, and a working answer is remembered for next time\n\nA source naming a path that cannot be opened is **skipped** rather than fatal, so the next source gets\nits turn. The reason goes to the server log, and once some later source opens, `ea_get_model_info`\nlists it under `skipped`. That is deliberate — a sample value left in an `env` block would otherwise\noutrank every answer you could give, and answering the prompt would never help. The cost is that a\ngenuine typo is demoted quietly, so check `ea_get_model_info` if the server opens a different model\nthan you expected.\n\nSkipping is only worth it when an answer can take the skipped source's place, so two cases stay\nfatal: a path you passed **on the command line** (that is this run's explicit instruction, not a\nstale default), and any broken source in a client that **cannot show a prompt** — falling through\nthere would quietly open some other model instead of telling you.\n\nAnswers are remembered per machine, in `%APPDATA%\\enterprise-architect-mcp\\` on Windows,\n`~/Library/Application Support/enterprise-architect-mcp/` on macOS, and `$XDG_CONFIG_HOME` (or\n`~/.config`) elsewhere; set `EA_MCP_CONFIG_DIR` to keep that file somewhere else. A path that does\nnot open is never remembered, so asking again is enough to correct a mistyped answer.\n\nIf the path points to a **directory**, the server automatically picks the newest `.qea` file by\nmodification time. Pointing at your export folder means new exports are picked up without\nreconfiguring anything.\n\n### Name ordering\n\nMatching is locale-independent — search folds case and diacritics across European Latin alphabets,\nso `Straße`, `Łódź` and `Győr` are found however they are typed or entity-encoded.\n\nThe enumeration tools — `ea_search`, `ea_list_elements`, `ea_list_diagrams` — do not order by name\nat all. They order by the model's internal identity: stable and repeatable, but artificial, so\nnothing should be read into which row follows which. That is a deliberate trade. Alphabetical\nordering under SQLite's binary collation sorts every accented initial after `Z`, and since these\ntools return a window rather than the whole set, it does not merely reorder the list — it pushes\naccented names out of the window entirely. Measured on a real export, names with an accented\ninitial filled 1.3% of visible slots under binary ordering against 3.0% under identity order, in a\nmodel where they make up 3.9% of all names.\n\nOnly `ea_get_scenarios` still orders names by locale, where the whole set is always returned and no\nname can be cut off. `EA_LOCALE` pins that ordering to a BCP 47 tag (`sk`, `pl`, `hu`, `de`, …) in\nan `env` block or system env; unset, the host default applies. It does not affect matching.\n\n### Paging and narrowing\n\nThe enumeration tools return a window, not a sample. Each response carries `totalMatched`,\n`returned`, `offset` and `truncated`, and when rows remain, a `continuation` naming the next call —\nfollowing it repeatedly visits every match once and terminates. Raising `limit` is not the way to\nread a large set; advancing `offset` is.\n\nWhen far more rows match than one window could hold, the response also carries a `breakdown` of how\nthey distribute. Its keys are parameter names and its values are argument values, so a breakdown is\na prompt to narrow — by `objectType`, `stereotype`, `diagramType`, or, for `ea_search` when the\nresult isn't already scoped, by `packageScope` (reported as the matching package's id, which the\nnext call can pass straight back) — rather than to page through thousands of rows.\n\n### Naming the path up front\n\nIf you would rather never see the prompt — a CI job, a shared image, or simply a preference — put\nthe path in a gitignored `.env` in the working directory. Copy the template:\n\n```powershell\nCopy-Item .env.example .env\n```\n\nThen set your local path in `.env`:\n\n```ini\nEA_QEA_PATH=C:\\EA\\exports\\model.qea\n```\n\nA directory works too — the newest `.qea` file in it is used:\n\n```ini\nEA_QEA_PATH=C:\\EA\\exports\\\n```\n\nThe `.env` file is gitignored — each developer sets their own path without affecting the shared\nconfig. It is also never committed, which is why it is the one route every new user has to set up by\nhand; answering the prompt once is what makes that unnecessary.\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `ea_search` | Full-text search across elements, attributes, operations, and constraints. Case- and diacritic-insensitive across European Latin alphabets, decodes entity-encoded text. Each result carries the evidence for its match — the field, the attribute or operation it came from, and a snippet of the author's own text. Accepts a `packageScope` (package id or name) to restrict results to a package and its descendants, and reports a package breakdown axis when unscoped. |\n| `ea_get_element` | Full element detail — attributes, operations, diagrams it appears on, constraints (pre/post/invariant/process). Flags whether attribute multiplicity is contrastive. |\n| `ea_list_elements` | List elements in a package, optionally filtered by type. Windowed: reports the total and pages with `offset`. |\n| `ea_get_connectors` | Relationships for an element — includes feature-link resolution (which attribute/operation each end attaches to). `Generalization` connectors carry a `role` (`child`/`parent`) on each end; filter `connectorType: \"Generalization\"` with `direction: \"incoming\"`/`\"outgoing\"` to list an element's direct children/parent(s) without a diagram. |\n| `ea_get_diagram_elements` | Elements and connectors on a diagram, including implied connectors and feature links. `elements` includes free-text `Note` diagram objects, which often carry a legend or abbreviation definitions. |\n| `ea_get_scenarios` | Use case scenario steps with all attributes (trigger, uses, result, link, state) and scenario notes. A step's `uses` may name a business rule or constraint by code — that code isn't independently searchable, it's retrieved via `ea_get_element` on the same element. |\n| `ea_get_package_tree` | Navigate the package hierarchy with recursive depth. |\n| `ea_list_diagrams` | Search diagrams by name, type and package. Windowed like the tools above. |\n| `ea_resolve` | Resolve analyst references (braced GUID or plain name) to model candidates with full package path. Falls back to name-prefix matching for analyst codes; every candidate carries a `match` of `guid`, `exact`, or `prefix`. |\n| `ea_get_schema` | Introspect the model's database schema — tables, columns, indexes, rowid alias. |\n| `ea_get_model_info` | Identity of the open export — file name, size, modification date, server version, and which configuration source the path came from. |\n\n### Response contract\n\nEvery tool returns structured JSON with:\n\n- `_meta.sourceTables` — which database tables were consulted\n- `totalMatched` / `returned` / `truncated` — completeness metadata on every collection\n- `continuation` — exact call to retrieve the full set when truncated\n- `isError: true` + `{ error: \"not_found\" }` for non-existent subjects (distinct from empty results)\n\nTwo fields exist to stop an inexact answer from being read as a confirmed one:\n\n- `ea_resolve` — `match` is always present; only `prefix` is an inexact match\n- `ea_get_element` — `_meta.attributes.multiplicityIsUniform: true` means the element's attributes show no multiplicity contrast, so `1..1` is not evidence of requiredness\n\n## Example Prompts\n\nOnce connected, try prompts like:\n\n- \"Search for elements related to 'legal entity'\"\n- \"Show me the package structure under the root\"\n- \"What are the use case scenarios for UC_SUBMIT_APPLICATION?\"\n- \"What elements and connectors are on diagram 0103 Application Processing?\"\n- \"Resolve the reference {3F2A7C10-5B4D-4e8a-9C1F-27D6E8B0A4F3}\"\n- \"What columns does t_connector have?\"\n- \"Which diagrams does element a7680 appear on?\"\n\n## License\n\nCopyright (c) 2026 Michal Mracka\n\nLicensed under the EUPL — see [LICENSE](LICENSE) for the full text.\n\n",
  "bytes": 12730,
  "sha": "d0a9bce2d2b1574d0906107388fb9e90cb2ff13359aab9d59f87b9550b848fdc",
  "repo_slug": "mm6502/enterprise-architect-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mm6502_enterprise_architect_mc_10d273d8/readme"
}