enterprise-architect-mcp 2.3.0 → 3.0.0

package/README.md

@@ -5,6 +5,7 @@
 [![License: EUPL-1.2](https://img.shields.io/badge/license-EUPL--1.2-blue.svg)](LICENSE)
 [![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)
 [![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)
+[![Compound Engineering](https://img.shields.io/badge/Built_with-Compound_Engineering-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
 
 A 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.
 
@@ -89,6 +90,18 @@ you can name the path in an `env` block:
 
 To run straight from source instead of npm, use `"args": ["-y", "github:mm6502/enterprise-architect-mcp"]`.
 
+## Example Prompts
+
+Once connected, try prompts like:
+
+- "Search for elements related to 'legal entity'"
+- "Show me the package structure under the root"
+- "What are the use case scenarios for UC_SUBMIT_APPLICATION?"
+- "What elements and connectors are on diagram 0103 Application Processing?"
+- "Resolve the reference {3F2A7C10-5B4D-4e8a-9C1F-27D6E8B0A4F3}"
+- "What columns does t_connector have?"
+- "Which diagrams does element a7680 appear on?"
+
 ## Configuration
 
 The server does not need a path to start. It looks for one when an agent first queries the model, and
@@ -100,60 +113,6 @@ takes the first source that actually opens:
 4. **A remembered answer** — whatever you last told the prompt
 5. **The prompt** — the client asks, and a working answer is remembered for next time
 
-A source naming a path that cannot be opened is **skipped** rather than fatal, so the next source gets
-its turn. The reason goes to the server log, and once some later source opens, `ea_get_model_info`
-lists it under `skipped`. That is deliberate — a sample value left in an `env` block would otherwise
-outrank every answer you could give, and answering the prompt would never help. The cost is that a
-genuine typo is demoted quietly, so check `ea_get_model_info` if the server opens a different model
-than you expected.
-
-Skipping is only worth it when an answer can take the skipped source's place, so two cases stay
-fatal: a path you passed **on the command line** (that is this run's explicit instruction, not a
-stale default), and any broken source in a client that **cannot show a prompt** — falling through
-there would quietly open some other model instead of telling you.
-
-Answers are remembered per machine, in `%APPDATA%\enterprise-architect-mcp\` on Windows,
-`~/Library/Application Support/enterprise-architect-mcp/` on macOS, and `$XDG_CONFIG_HOME` (or
-`~/.config`) elsewhere; set `EA_MCP_CONFIG_DIR` to keep that file somewhere else. A path that does
-not open is never remembered, so asking again is enough to correct a mistyped answer.
-
-If the path points to a **directory**, the server automatically picks the newest `.qea` file by
-modification time. Pointing at your export folder means new exports are picked up without
-reconfiguring anything.
-
-### Name ordering
-
-Matching is locale-independent — search folds case and diacritics across European Latin alphabets,
-so `Straße`, `Łódź` and `Győr` are found however they are typed or entity-encoded.
-
-The enumeration tools — `ea_search`, `ea_list_elements`, `ea_list_diagrams` — do not order by name
-at all. They order by the model's internal identity: stable and repeatable, but artificial, so
-nothing should be read into which row follows which. That is a deliberate trade. Alphabetical
-ordering under SQLite's binary collation sorts every accented initial after `Z`, and since these
-tools return a window rather than the whole set, it does not merely reorder the list — it pushes
-accented names out of the window entirely. Measured on a real export, names with an accented
-initial filled 1.3% of visible slots under binary ordering against 3.0% under identity order, in a
-model where they make up 3.9% of all names.
-
-Only `ea_get_scenarios` still orders names by locale, where the whole set is always returned and no
-name can be cut off. `EA_LOCALE` pins that ordering to a BCP 47 tag (`sk`, `pl`, `hu`, `de`, …) in
-an `env` block or system env; unset, the host default applies. It does not affect matching.
-
-### Paging and narrowing
-
-The enumeration tools return a window, not a sample. Each response carries `totalMatched`,
-`returned`, `offset` and `truncated`, and when rows remain, a `continuation` naming the next call —
-following it repeatedly visits every match once and terminates. Raising `limit` is not the way to
-read a large set; advancing `offset` is.
-
-When far more rows match than one window could hold, the response also carries a `breakdown` of how
-they distribute. Its keys are parameter names and its values are argument values, so a breakdown is
-a prompt to narrow — by `objectType`, `stereotype`, `diagramType`, or, for `ea_search` when the
-result isn't already scoped, by `packageScope` (reported as the matching package's id, which the
-next call can pass straight back) — rather than to page through thousands of rows.
-
-### Naming the path up front
-
 If you would rather never see the prompt — a CI job, a shared image, or simply a preference — put
 the path in a gitignored `.env` in the working directory. Copy the template:
 
@@ -167,7 +126,9 @@ Then set your local path in `.env`:
 EA_QEA_PATH=C:\EA\exports\model.qea
 ```
 
-A directory works too — the newest `.qea` file in it is used:
+If the path points to a **directory** instead of a file, the server automatically picks the newest
+`.qea` file in it by modification time — point it at your export folder and new exports are picked up
+without reconfiguring anything:
 
 ```ini
 EA_QEA_PATH=C:\EA\exports\
@@ -177,15 +138,33 @@ The `.env` file is gitignored — each developer sets their own path without aff
 config. It is also never committed, which is why it is the one route every new user has to set up by
 hand; answering the prompt once is what makes that unnecessary.
 
+A source naming a path that cannot be opened is **skipped** rather than fatal, so the next source gets
+its turn. The reason goes to the server log, and once some later source opens, `ea_get_model_info`
+lists it under `skipped`. That is deliberate — a sample value left in an `env` block would otherwise
+outrank every answer you could give, and answering the prompt would never help. The cost is that a
+genuine typo is demoted quietly, so check `ea_get_model_info` if the server opens a different model
+than you expected.
+
+Skipping is only worth it when an answer can take the skipped source's place, so two cases stay
+fatal: a path you passed **on the command line** (that is this run's explicit instruction, not a
+stale default), and any broken source in a client that **cannot show a prompt** — falling through
+there would quietly open some other model instead of telling you.
+
+Answers are remembered per machine, in `%APPDATA%\enterprise-architect-mcp\` on Windows,
+`~/Library/Application Support/enterprise-architect-mcp/` on macOS, and `$XDG_CONFIG_HOME` (or
+`~/.config`) elsewhere; set `EA_MCP_CONFIG_DIR` to keep that file somewhere else. A path that does
+not open is never remembered, so asking again is enough to correct a mistyped answer.
+
 ## Available Tools
 
 | Tool | Description |
 |------|-------------|
-| `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. |
+| `ea_search` | Full-text search across elements, attributes, operations, and constraints. Takes `requiredTerms`, a list of terms every one of which must occur somewhere in an element's searchable text (conjunction) — terms need not share a field, but sharing one ranks higher. `boostAnyOf` is an optional list of further terms that promote a result's rank without ever excluding on that basis. 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. |
+| `ea_search_and_any_of` | Same matching as `ea_search`, plus `andAnyOf`: an optional list of terms where a result must satisfy `requiredTerms` **and** at least one `andAnyOf` term — narrowing rather than reordering. Use this instead of `ea_search` when an alternative term should exclude, not just promote. |
 | `ea_get_element` | Full element detail — attributes, operations, diagrams it appears on, constraints (pre/post/invariant/process). Flags whether attribute multiplicity is contrastive. |
 | `ea_list_elements` | List elements in a package, optionally filtered by type. Windowed: reports the total and pages with `offset`. |
-| `ea_get_connectors` | Relationships for an element — includes feature-link resolution (which attribute/operation each end attaches to). |
-| `ea_get_diagram_elements` | Elements and connectors on a diagram, including implied connectors and feature links. |
+| `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. |
+| `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. |
 | `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. |
 | `ea_get_package_tree` | Navigate the package hierarchy with recursive depth. |
 | `ea_list_diagrams` | Search diagrams by name, type and package. Windowed like the tools above. |
@@ -207,21 +186,41 @@ Two fields exist to stop an inexact answer from being read as a confirmed one:
 - `ea_resolve` — `match` is always present; only `prefix` is an inexact match
 - `ea_get_element` — `_meta.attributes.multiplicityIsUniform: true` means the element's attributes show no multiplicity contrast, so `1..1` is not evidence of requiredness
 
-## Example Prompts
+## How Results Are Ordered, Paged, and Narrowed
 
-Once connected, try prompts like:
+### Name ordering
 
-- "Search for elements related to 'legal entity'"
-- "Show me the package structure under the root"
-- "What are the use case scenarios for UC_SUBMIT_APPLICATION?"
-- "What elements and connectors are on diagram 0103 Application Processing?"
-- "Resolve the reference {3F2A7C10-5B4D-4e8a-9C1F-27D6E8B0A4F3}"
-- "What columns does t_connector have?"
-- "Which diagrams does element a7680 appear on?"
+Matching is locale-independent — search folds case and diacritics across European Latin alphabets,
+so `Straße`, `Łódź` and `Győr` are found however they are typed or entity-encoded.
+
+The enumeration tools — `ea_search`, `ea_list_elements`, `ea_list_diagrams` — do not order by name
+at all. They order by the model's internal identity: stable and repeatable, but artificial, so
+nothing should be read into which row follows which. That is a deliberate trade. Alphabetical
+ordering under SQLite's binary collation sorts every accented initial after `Z`, and since these
+tools return a window rather than the whole set, it does not merely reorder the list — it pushes
+accented names out of the window entirely. Measured on a real export, names with an accented
+initial filled 1.3% of visible slots under binary ordering against 3.0% under identity order, in a
+model where they make up 3.9% of all names.
+
+Only `ea_get_scenarios` still orders names by locale, where the whole set is always returned and no
+name can be cut off. `EA_LOCALE` pins that ordering to a BCP 47 tag (`sk`, `pl`, `hu`, `de`, …) in
+an `env` block or system env; unset, the host default applies. It does not affect matching.
+
+### Paging and narrowing
+
+The enumeration tools return a window, not a sample. Each response carries `totalMatched`,
+`returned`, `offset` and `truncated`, and when rows remain, a `continuation` naming the next call —
+following it repeatedly visits every match once and terminates. Raising `limit` is not the way to
+read a large set; advancing `offset` is.
+
+When far more rows match than one window could hold, the response also carries a `breakdown` of how
+they distribute. Its keys are parameter names and its values are argument values, so a breakdown is
+a prompt to narrow — by `objectType`, `stereotype`, `diagramType`, or, for `ea_search` when the
+result isn't already scoped, by `packageScope` (reported as the matching package's id, which the
+next call can pass straight back) — rather than to page through thousands of rows.
 
 ## License
 
 Copyright (c) 2026 Michal Mracka
 
 Licensed under the EUPL — see [LICENSE](LICENSE) for the full text.
-

package/dist/tools/connectors.js

@@ -46,7 +46,7 @@ function parseFeatureLinks(db, styleEx) {
     return { sourceFeature, targetFeature };
 }
 export function configureConnectorTools(server, model) {
-    server.tool("ea_get_connectors", "Get all relationships (connectors) for a given element. `connectors` lists what the element is connected to and how (Realisation, Dependency, Association, etc.), each entry naming its `source` and `dest` ends. Feature links show which specific attribute or operation each end attaches to.", {
+    server.tool("ea_get_connectors", "Get all relationships (connectors) for a given element. `connectors` lists what the element is connected to and how (Realisation, Dependency, Association, etc.), each entry naming its `source` and `dest` ends. For Generalization connectors, `source` is always the specific (child) type and `dest` the general (parent) type \u2014 each end also carries a `role` making this explicit without needing to reason about direction. Filter by `connectorType` and `direction` to list an element's direct children (incoming Generalization) or direct parent(s) (outgoing Generalization) without a diagram. Feature links show which specific attribute or operation each end attaches to.", {
         elementId: z.coerce.number().describe("The Object_ID of the element to get connectors for"),
         connectorType: z
             .string()
@@ -113,8 +113,9 @@ export function configureConnectorTools(server, model) {
                     destCard: r.DestCard,
                     sourceRole: r.SourceRole || null,
                     destRole: r.DestRole || null,
-                    source: { id: r.Start_Object_ID, name: r.SourceName, type: r.SourceType, stereotype: r.SourceStereotype },
-                    dest: { id: r.End_Object_ID, name: r.DestName, type: r.DestType, stereotype: r.DestStereotype },
+                    // Generalization: Start_Object_ID is always the specific (child) type, End_Object_ID the general (parent) type.
+                    source: { id: r.Start_Object_ID, name: r.SourceName, type: r.SourceType, stereotype: r.SourceStereotype, ...(r.Connector_Type === "Generalization" ? { role: "child" } : {}) },
+                    dest: { id: r.End_Object_ID, name: r.DestName, type: r.DestType, stereotype: r.DestStereotype, ...(r.Connector_Type === "Generalization" ? { role: "parent" } : {}) },
                     sourceFeature,
                     targetFeature,
                 };

package/dist/tools/diagrams.js

@@ -44,7 +44,7 @@ function parseFeatureLinks(db, styleEx) {
     return { sourceFeature, targetFeature };
 }
 export function configureDiagramTools(server, model) {
-    server.tool("ea_get_diagram_elements", "Get all elements and connectors placed on a specific diagram: the `diagram` itself, plus `elements` and `connectors`. Connectors include feature-link resolution showing which attribute or operation each end attaches to. The connector list is the union of explicit t_diagramlinks rows and implied connectors (both ends on the diagram).", {
+    server.tool("ea_get_diagram_elements", "Get all elements and connectors placed on a specific diagram: the `diagram` itself, plus `elements` and `connectors`. `elements` already includes free-text `Note` diagram objects, which often carry a legend or abbreviation definitions an agent would otherwise miss. Connectors include feature-link resolution showing which attribute or operation each end attaches to. The connector list is the union of explicit t_diagramlinks rows and implied connectors (both ends on the diagram).", {
         diagramId: z.coerce.number().describe("The Diagram_ID to get elements for"),
     }, READ_ONLY, async ({ diagramId }) => {
         const db = await model.database();

package/dist/tools/elements.js

@@ -39,7 +39,7 @@ export function configureElementTools(server, model) {
                 type: a.Type,
                 scope: a.Scope,
                 stereotype: a.Stereotype,
-                notes: a.Notes,
+                notes: decodeEntities(a.Notes),
                 multiplicity: formatMultiplicity(a),
                 default: a.Default,
             }));
@@ -66,12 +66,12 @@ export function configureElementTools(server, model) {
                     returnType: op.Type,
                     scope: op.Scope,
                     stereotype: op.Stereotype,
-                    notes: op.Notes,
+                    notes: decodeEntities(op.Notes),
                     parameters: params.map((p) => ({
                         name: p.Name,
                         type: p.Type,
                         kind: p.Kind,
-                        notes: p.Notes,
+                        notes: decodeEntities(p.Notes),
                     })),
                 };
             });

package/dist/tools/search.js

@@ -49,10 +49,16 @@ function excerptAround(original, folded, foldedQuery, budget) {
     const tail = hi < words.length - 1 ? "…" : "";
     return { text: head + original.slice(words[lo][0], words[hi][1]) + tail, truncated: head !== "" || tail !== "" };
 }
-/** True when the query begins somewhere other than mid-word. */
+/**
+ * True when the query begins somewhere other than mid-word — including at the very start of
+ * the text. Single-term ranking never reaches this for a position-0 match (rank 1, `startsWith`,
+ * already wins first), so widening it to treat idx 0 as a boundary is safe there; it matters
+ * once several terms are checked independently (R7), where an earlier term's own position-0
+ * match must not be misread as failing the boundary test.
+ */
 function startsAtWordBoundary(text, query) {
-    for (let idx = text.indexOf(query); idx > 0; idx = text.indexOf(query, idx + 1)) {
-        if (!/[\p{L}\p{N}]/u.test(text[idx - 1]))
+    for (let idx = text.indexOf(query); idx >= 0; idx = text.indexOf(query, idx + 1)) {
+        if (idx === 0 || !/[\p{L}\p{N}]/u.test(text[idx - 1]))
             return true;
     }
     return false;
@@ -87,6 +93,136 @@ function scoreMatch(entry, foldedQuery) {
         return { rank: entry.sourceField === "Name" ? 7 : 9, coverage: 0 };
     return { rank: 10, coverage: 0 };
 }
+/** Below every single-field ladder rank (0-10), so R1's cross-field match never outranks one. */
+const SPREAD_RANK = 11;
+/**
+ * Whether every supplied term occurs in `text`, each immediately after the previous one save
+ * for a run of non-alphanumeric characters — i.e. adjacent in the caller's own order (R8).
+ * Meaningless for a single term (there is nothing to be adjacent to), so it is always false
+ * then, which is what keeps this out of the single-term path entirely.
+ */
+function isPhraseGrade(text, foldedTerms) {
+    if (foldedTerms.length < 2)
+        return false;
+    const escaped = foldedTerms.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    return new RegExp(escaped.join("[^\\p{L}\\p{N}]*"), "u").test(text);
+}
+/**
+ * How far apart several required terms sit in the text that carried all of them — the smallest
+ * span containing at least one occurrence of every term. Smaller is more proximate (R10). Always
+ * 0 for a single term, so it never perturbs the single-term freeze (R3): every candidate ties
+ * at 0 and the comparison falls straight through to the next tiebreak, exactly as it does today.
+ * A term repeated elsewhere in the text must not make a genuinely tight cluster look far apart,
+ * so every occurrence of every term is a candidate, not just each term's first (the classic
+ * "smallest range covering every list" problem: merge all occurrences by position, then slide a
+ * window until it covers every term, shrinking from the left while it still does).
+ */
+function termProximity(text, foldedTerms) {
+    if (foldedTerms.length < 2)
+        return 0;
+    const occurrences = [];
+    foldedTerms.forEach((t, term) => {
+        for (let at = text.indexOf(t); at >= 0; at = text.indexOf(t, at + 1)) {
+            occurrences.push({ pos: at, term });
+        }
+    });
+    if (occurrences.length === 0)
+        return 0;
+    occurrences.sort((a, b) => a.pos - b.pos);
+    const counts = new Array(foldedTerms.length).fill(0);
+    let distinct = 0;
+    let left = 0;
+    let best = Infinity;
+    for (let right = 0; right < occurrences.length; right++) {
+        if (counts[occurrences[right].term]++ === 0)
+            distinct++;
+        while (distinct === foldedTerms.length) {
+            best = Math.min(best, occurrences[right].pos - occurrences[left].pos);
+            if (--counts[occurrences[left].term] === 0)
+                distinct--;
+            left++;
+        }
+    }
+    return best === Infinity ? 0 : best;
+}
+/**
+ * Generalises scoreMatch to several required terms, reducing exactly to it for one term —
+ * that identity is what lets R3's freeze hold by construction rather than by a parallel code
+ * path. Exact and prefix (ranks 0-1) stay single-term concepts: neither has a natural meaning
+ * once more than one distinct required term is involved. Word-boundary (rank 2) generalises
+ * cleanly instead (R7): it holds only when every term independently starts at a boundary,
+ * otherwise the match settles at the ladder's infix rank (3). Every other bucket depends only
+ * on (sourceTable, sourceField), so it is unaffected by term count. A phrase-grade match (R8)
+ * then promotes half a rank within whichever bucket it already landed in — never crossing into
+ * a neighbouring field's territory, which is what keeps R9's resolvable-to-one-field guarantee
+ * intact. Coverage becomes the summed term length over the text length, capped at 1 — how this
+ * should really work for a multi-term match is an open question (see Outstanding Questions),
+ * and this is a placeholder, not a final answer.
+ */
+function scoreMultiMatch(entry, foldedTerms) {
+    if (foldedTerms.length === 1)
+        return { ...scoreMatch(entry, foldedTerms[0]), proximity: 0 };
+    const text = entry.foldedText;
+    const coverage = text.length > 0
+        ? Math.min(1, foldedTerms.reduce((sum, t) => sum + t.length, 0) / text.length)
+        : 0;
+    let rank;
+    if (entry.sourceTable === "t_object" && entry.sourceField === "Name") {
+        rank = foldedTerms.every((t) => startsAtWordBoundary(text, t)) ? 2 : 3;
+    }
+    else {
+        rank = scoreMatch(entry, foldedTerms[0]).rank;
+    }
+    if (isPhraseGrade(text, foldedTerms))
+        rank -= 0.5;
+    return { rank, coverage, proximity: termProximity(text, foldedTerms) };
+}
+/**
+ * Whether every required term occurs somewhere in this object's searchable text (R1), and how
+ * it ranks. A single entry carrying every term ranks via the existing ladder (R7); an object
+ * whose terms are only found spread across separate entries still matches, but ranks below
+ * every single-field tier — R1's "ranking preference, not a condition of matching". Reduces
+ * to today's single-term matching and ranking exactly when only one term is supplied, since
+ * every entry containing that one term trivially "carries every term", and proximity is always
+ * 0 for one term (see termProximity), so the R10/R11 tiebreak this adds is a no-op there too.
+ */
+function matchObject(objEntries, foldedTerms) {
+    for (const term of foldedTerms) {
+        if (!objEntries.some((e) => e.foldedText.includes(term)))
+            return null;
+    }
+    let best;
+    for (const e of objEntries) {
+        if (!foldedTerms.every((t) => e.foldedText.includes(t)))
+            continue;
+        const { rank, coverage, proximity } = scoreMultiMatch(e, foldedTerms);
+        const better = !best ||
+            rank < best.rank ||
+            (rank === best.rank && coverage > best.coverage) ||
+            (rank === best.rank && coverage === best.coverage && proximity < best.proximity);
+        if (better) {
+            best = { rank, coverage, proximity, matchedIn: `${e.sourceTable}.${e.sourceField}` };
+        }
+    }
+    if (best)
+        return best;
+    // Spread: no single entry carries every term. Coverage is the average of each term's own
+    // best-entry coverage — like the rank placeholder above, an interim answer, not a final one.
+    // Proximity has no shared text to measure across separate entries, so it stays neutral (0).
+    let coverageSum = 0;
+    for (const term of foldedTerms) {
+        let bestCoverage = 0;
+        for (const e of objEntries) {
+            if (!e.foldedText.includes(term))
+                continue;
+            const { coverage } = scoreMatch(e, term);
+            if (coverage > bestCoverage)
+                bestCoverage = coverage;
+        }
+        coverageSum += bestCoverage;
+    }
+    return { rank: SPREAD_RANK, coverage: coverageSum / foldedTerms.length, proximity: 0, matchedIn: null };
+}
 function buildCorpus(db) {
     const cached = corpora.get(db);
     if (cached)
@@ -156,12 +292,14 @@ function originalFor(entry, src) {
 }
 /**
  * Why each windowed element matched. Scanning is confined to the window, so the cost is
- * bounded by what the response shows rather than by the corpus.
+ * bounded by what the response shows rather than by the corpus. Matches an entry against any
+ * of the required terms (not all of them, unlike matchObject) since evidence is about what
+ * each field contributed, and reduces to single-term behaviour exactly when only one is given.
  */
-function collectEvidence(db, entries, rows, windowIds, foldedQuery) {
+function collectEvidence(db, entries, rows, windowIds, foldedTerms) {
     const hits = new Map();
     for (const entry of entries) {
-        if (!windowIds.has(entry.objectId) || !entry.foldedText.includes(foldedQuery))
+        if (!windowIds.has(entry.objectId) || !foldedTerms.some((t) => entry.foldedText.includes(t)))
             continue;
         const list = hits.get(entry.objectId);
         if (list)
@@ -172,17 +310,20 @@ function collectEvidence(db, entries, rows, windowIds, foldedQuery) {
     const kept = new Map();
     for (const [objectId, list] of hits) {
         const ranked = list
-            .map((e) => ({ e, ...scoreMatch(e, foldedQuery) }))
-            .sort((a, b) => a.rank - b.rank || b.coverage - a.coverage || a.e.sourceId - b.e.sourceId)
+            .map((e) => {
+            const present = foldedTerms.filter((t) => e.foldedText.includes(t));
+            return { e, present, ...scoreMultiMatch(e, present) };
+        })
+            .sort((a, b) => a.rank - b.rank || b.coverage - a.coverage || a.proximity - b.proximity || a.e.sourceId - b.e.sourceId)
             .slice(0, MAX_INLINE_MATCHES)
-            .map((r) => r.e);
+            .map((r) => ({ entry: r.e, term: r.present[0] }));
         kept.set(objectId, { entries: ranked, totalMatched: list.length });
     }
     const attributeIds = new Set();
     const operationIds = new Set();
     const constraintOwners = new Set();
     for (const { entries: shown } of kept.values()) {
-        for (const e of shown) {
+        for (const { entry: e } of shown) {
             if (e.sourceTable === "t_attribute")
                 attributeIds.add(e.sourceId);
             else if (e.sourceTable === "t_operation")
@@ -208,11 +349,11 @@ function collectEvidence(db, entries, rows, windowIds, foldedQuery) {
     const evidence = new Map();
     for (const [objectId, { entries: shown, totalMatched }] of kept) {
         const items = [];
-        for (const entry of shown) {
+        for (const { entry, term } of shown) {
             const original = originalFor(entry, src);
             if (!original)
                 continue;
-            const excerpt = excerptAround(original.text, entry.foldedText, foldedQuery, SNIPPET_CHARS);
+            const excerpt = excerptAround(original.text, entry.foldedText, term, SNIPPET_CHARS);
             items.push({
                 matchedIn: `${entry.sourceTable}.${entry.sourceField}`,
                 sourceId: entry.sourceId,
@@ -225,186 +366,279 @@ function collectEvidence(db, entries, rows, windowIds, foldedQuery) {
     }
     return evidence;
 }
-export function configureSearchTools(server, model) {
-    server.tool("ea_search", "Search Enterprise Architect model elements by name, alias, notes, attribute names/notes, operation names/notes, or constraint notes. Matching is case- and diacritic-insensitive across European Latin alphabets and sees through entity-encoded text. Matching elements are returned in `results`, strongest match first, each with a decoded note preview and a truncation flag; equally strong matches fall back to the model's internal identity, a stable but artificial order. Each result also carries `matches`, the evidence for why it was returned: the field that matched, the id and name of the attribute, operation or constraint it came from, and a snippet of the author's own text around the match. Evidence is strongest-first and capped, and `_meta.matches` on the result reports how many matches were found and how many were withheld. The note preview centres on the match when the element's own note is what matched. `packageScope` restricts results to a package (given as its id or its name) and its descendants. Walk a large result set with `offset` rather than a larger `limit`; while rows remain, `continuation` names the next call. When far more elements match than one window can hold, `breakdown` reports how they distribute — by `objectType`, `stereotype`, or, unless already scoped, by `packageScope` (reported as the matching package's id, which the next call can pass straight back) — so the next call can narrow instead of paging.", {
-        query: z.string().describe("Search term to find across all model text (names, notes, aliases, attributes, operations, constraints)"),
-        objectType: z
-            .string()
-            .optional()
-            .describe("Filter by object type (e.g., Class, UseCase, Activity, Screen, Requirement, Interface, Component)"),
-        stereotype: z.string().optional().describe("Filter by stereotype"),
-        packageScope: z
-            .union([z.number().int(), z.string()])
-            .optional()
-            .describe("Restrict results to this package and its descendants, given as a package id or name"),
-        limit: limitParam(25),
-        offset: offsetParam,
-    }, READ_ONLY, async ({ query, objectType, stereotype, packageScope, limit, offset }) => {
-        const db = await model.database();
-        try {
-            let subtree;
-            if (packageScope !== undefined) {
-                const resolution = resolvePackageScope(db, packageScope);
-                if (resolution.kind === "not_found") {
-                    return {
-                        content: [{ type: "text", text: JSON.stringify({
-                                    error: "not_found",
-                                    message: `Package scope "${packageScope}" was not found.`,
-                                    packageScope,
-                                }, null, 2) }],
-                        isError: true,
-                    };
-                }
-                if (resolution.kind === "ambiguous") {
-                    return {
-                        content: [{ type: "text", text: JSON.stringify({
-                                    error: "ambiguous_package",
-                                    message: `Package scope "${packageScope}" matches more than one package; use a package id instead.`,
-                                    candidates: resolution.candidates,
-                                }, null, 2) }],
-                        isError: true,
-                    };
-                }
-                subtree = getPackageSubtree(db, resolution.packageId);
-            }
-            const entries = buildCorpus(db);
-            const foldedQuery = foldText(query).trim();
-            if (foldedQuery.length === 0) {
+const REQUIRED_TERMS_PARAM = z
+    .array(z.string())
+    .min(1)
+    .max(10)
+    .describe("Terms every one of which must occur somewhere in the element's searchable text (names, notes, aliases, attributes, operations, constraints); terms need not share a field; capped at 10");
+const OBJECT_TYPE_PARAM = z
+    .string()
+    .optional()
+    .describe("Filter by object type (e.g., Class, UseCase, Activity, Screen, Requirement, Interface, Component)");
+const STEREOTYPE_PARAM = z.string().optional().describe("Filter by stereotype");
+const PACKAGE_SCOPE_PARAM = z
+    .union([z.number().int(), z.string()])
+    .optional()
+    .describe("Restrict results to this package and its descendants, given as a package id or name");
+/**
+ * Shared by both tools: `ea_search`'s required-term matching, ranking and response shape are
+ * identical either way. Only what an alternatives match does differs — boost promotes a tier
+ * within the same rank without excluding anything, filter removes an object lacking any
+ * alternative entirely — so that is the one thing this takes as a parameter.
+ */
+async function runSearch(db, toolName, altParamName, altMode, args, alternatives) {
+    const { requiredTerms, objectType, stereotype, packageScope, limit, offset } = args;
+    try {
+        let subtree;
+        if (packageScope !== undefined) {
+            const resolution = resolvePackageScope(db, packageScope);
+            if (resolution.kind === "not_found") {
                 return {
                     content: [{ type: "text", text: JSON.stringify({
-                                results: [],
-                                totalMatched: 0,
-                                returned: 0,
-                                offset,
-                                truncated: false,
-                                _meta: { sourceTables: ["t_object", "t_attribute", "t_operation", "t_objectconstraint", "t_package"] },
-                                error: "Query is empty after normalization.",
+                                error: "not_found",
+                                message: `Package scope "${packageScope}" was not found.`,
+                                packageScope,
                             }, null, 2) }],
+                    isError: true,
                 };
             }
-            // Find matching object IDs with match quality ranking
-            const matchMap = new Map();
-            for (const entry of entries) {
-                if (!entry.foldedText.includes(foldedQuery))
-                    continue;
-                const { rank, coverage } = scoreMatch(entry, foldedQuery);
-                const existing = matchMap.get(entry.objectId);
-                if (existing && (existing.rank < rank || (existing.rank === rank && existing.coverage >= coverage)))
-                    continue;
-                matchMap.set(entry.objectId, { rank, coverage, matchedIn: `${entry.sourceTable}.${entry.sourceField}` });
-            }
-            if (matchMap.size === 0) {
+            if (resolution.kind === "ambiguous") {
                 return {
-                    content: [{
-                            type: "text",
-                            text: JSON.stringify({
-                                results: [],
-                                totalMatched: 0,
-                                returned: 0,
-                                offset,
-                                truncated: false,
-                                _meta: { sourceTables: ["t_object", "t_attribute", "t_operation", "t_objectconstraint", "t_package"] },
-                            }, null, 2),
-                        }],
+                    content: [{ type: "text", text: JSON.stringify({
+                                error: "ambiguous_package",
+                                message: `Package scope "${packageScope}" matches more than one package; use a package id instead.`,
+                                candidates: resolution.candidates,
+                            }, null, 2) }],
+                    isError: true,
                 };
             }
-            // Strongest first, then identity: without the final tiebreak, paging a large
-            // tie could show the same row twice and never show another.
-            const sortedIds = [...matchMap.entries()]
-                .sort((a, b) => a[1].rank - b[1].rank || b[1].coverage - a[1].coverage || a[0] - b[0])
-                .map(([id]) => id);
-            // Build SQL to fetch matched elements with filters
-            let filterClauses = "";
-            const filterParams = [];
-            if (objectType) {
-                filterClauses += " AND o.Object_Type = ?";
-                filterParams.push(objectType);
-            }
-            if (stereotype) {
-                filterClauses += " AND o.Stereotype = ?";
-                filterParams.push(stereotype);
-            }
-            // Fetch all matching elements and apply filters
-            const placeholders = sortedIds.map(() => "?").join(",");
-            const sql = `
-          SELECT o.Object_ID, o.Object_Type, o.Name, o.Alias, o.Stereotype,
-                 o.Package_ID, p.Name as PackageName, o.Note
-          FROM t_object o
-          LEFT JOIN t_package p ON o.Package_ID = p.Package_ID
-          WHERE o.Object_ID IN (${placeholders})${filterClauses}
-        `;
-            const allRows = db.prepare(sql).all(...sortedIds, ...filterParams);
-            // Package_ID is on every fetched row, so scoping is a subtree membership check, not a query change.
-            const scopedRows = subtree ? allRows.filter((r) => subtree.has(r.Package_ID)) : allRows;
-            // IN (...) returns rows in whatever order the plan produces, so rank order is restored here.
-            const rowMap = new Map(scopedRows.map((r) => [r.Object_ID, r]));
-            const totalMatched = sortedIds.filter((id) => rowMap.has(id)).length;
-            const sorted = sortedIds
-                .filter((id) => rowMap.has(id))
-                .map((id) => rowMap.get(id));
-            const window = sorted.slice(offset, offset + limit);
-            const truncated = isTruncated(offset, window.length, totalMatched);
-            const evidence = collectEvidence(db, entries, rowMap, new Set(window.map((r) => r.Object_ID)), foldedQuery);
-            const results = window.map((r) => {
-                const decodedNote = decodeEntities(r.Note);
-                const matchedIn = matchMap.get(r.Object_ID)?.matchedIn ?? null;
-                // Previewing from the start hides the reason for a match that lies deeper in the note.
-                const notePreview = !decodedNote
-                    ? null
-                    : matchedIn === "t_object.Note"
-                        ? excerptAround(decodedNote, foldText(decodedNote), foldedQuery, NOTE_PREVIEW_CHARS).text
-                        : decodedNote.slice(0, NOTE_PREVIEW_CHARS);
-                const notePreviewTruncated = decodedNote != null && decodedNote.length > NOTE_PREVIEW_CHARS;
-                const matches = evidence.get(r.Object_ID);
-                return {
-                    Object_ID: r.Object_ID,
-                    Object_Type: r.Object_Type,
-                    Name: r.Name,
-                    Alias: r.Alias,
-                    Stereotype: r.Stereotype,
-                    Package_ID: r.Package_ID,
-                    PackageName: r.PackageName,
-                    NotePreview: notePreview,
-                    notePreviewTruncated,
-                    matchedIn,
-                    matches: matches?.items ?? [],
-                    _meta: {
-                        matches: {
-                            totalMatched: matches?.totalMatched ?? 0,
-                            returned: matches?.items.length ?? 0,
-                            truncated: (matches?.totalMatched ?? 0) > (matches?.items.length ?? 0),
-                        },
-                    },
-                };
-            });
-            const breakdown = breakdownApplies(totalMatched, limit)
-                ? buildBreakdown({
-                    objectType: objectType ? undefined : countBy(sorted, (r) => r.Object_Type),
-                    stereotype: stereotype ? undefined : countBy(sorted, (r) => r.Stereotype),
-                    packageScope: packageScope !== undefined ? undefined : countBy(sorted, (r) => r.Package_ID),
-                })
-                : undefined;
-            const continuation = buildContinuation("ea_search", { query, objectType, stereotype, packageScope, limit }, offset, results.length, totalMatched);
-            const response = {
-                results,
-                totalMatched,
-                returned: results.length,
-                offset,
-                truncated,
-                ...(breakdown ? { breakdown } : {}),
-                ...(continuation ? { continuation } : {}),
-                _meta: { sourceTables: ["t_object", "t_attribute", "t_operation", "t_objectconstraint", "t_package"] },
+            subtree = getPackageSubtree(db, resolution.packageId);
+        }
+        const entries = buildCorpus(db);
+        const normalizedTerms = requiredTerms.map((t) => foldText(t).trim());
+        if (normalizedTerms.some((t) => t.length === 0)) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            results: [],
+                            totalMatched: 0,
+                            returned: 0,
+                            offset,
+                            truncated: false,
+                            _meta: { sourceTables: ["t_object", "t_attribute", "t_operation", "t_objectconstraint", "t_package"] },
+                            error: "At least one requiredTerms entry is empty after normalization (whitespace-only or blank).",
+                        }, null, 2) }],
             };
+        }
+        // Duplicate terms would otherwise double-count coverage and cross the phrase-grade check
+        // against itself; a caller-supplied duplicate is a no-op, not a stronger requirement.
+        const foldedTerms = [...new Set(normalizedTerms)];
+        // Group once so a term found via one entry and another via a different entry of the
+        // same object still counts as a match (R1): terms need not share a field.
+        const byObject = new Map();
+        for (const entry of entries) {
+            const list = byObject.get(entry.objectId);
+            if (list)
+                list.push(entry);
+            else
+                byObject.set(entry.objectId, [entry]);
+        }
+        const matchMap = new Map();
+        for (const [objectId, objEntries] of byObject) {
+            const match = matchObject(objEntries, foldedTerms);
+            if (match)
+                matchMap.set(objectId, { ...match, boosted: false });
+        }
+        if (matchMap.size === 0) {
+            // R6: a caller guessing at stems cannot tell which one emptied the result without
+            // this — report each supplied term's own corpus-wide presence, independent of the
+            // others, rather than leaving them to re-guess the whole call.
+            const termMatches = requiredTerms.map((term) => {
+                const folded = foldText(term).trim();
+                return { term, matchedAnywhere: folded.length > 0 && entries.some((e) => e.foldedText.includes(folded)) };
+            });
             return {
-                content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            results: [],
+                            totalMatched: 0,
+                            returned: 0,
+                            offset,
+                            truncated: false,
+                            termMatches,
+                            _meta: { sourceTables: ["t_object", "t_attribute", "t_operation", "t_objectconstraint", "t_package"] },
+                        }, null, 2),
+                    }],
             };
         }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
+        // R4: the alternatives list is never required, and an empty one behaves as if omitted.
+        const foldedAlt = alternatives.map((t) => foldText(t).trim()).filter((t) => t.length > 0);
+        if (foldedAlt.length > 0) {
+            for (const [objectId, match] of matchMap) {
+                const objEntries = byObject.get(objectId);
+                const satisfied = objEntries.some((e) => foldedAlt.some((a) => e.foldedText.includes(a)));
+                if (altMode === "filter" && !satisfied)
+                    matchMap.delete(objectId);
+                else if (altMode === "boost" && satisfied)
+                    match.boosted = true;
+            }
+        }
+        if (matchMap.size === 0) {
+            // Filtering removed every required-term match; this is not R6's case (the required
+            // terms did match something), so no termMatches — just the plain empty shape.
             return {
-                content: [{ type: "text", text: `Error searching elements: ${msg}` }],
-                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            results: [],
+                            totalMatched: 0,
+                            returned: 0,
+                            offset,
+                            truncated: false,
+                            _meta: { sourceTables: ["t_object", "t_attribute", "t_operation", "t_objectconstraint", "t_package"] },
+                        }, null, 2),
+                    }],
             };
         }
+        // Strongest first, then identity: without the final tiebreak, paging a large tie could
+        // show the same row twice and never show another. `boosted` (R4's promotion) sits right
+        // after rank — ahead of coverage — since it is a within-rank preference, not a new tier;
+        // proximity (R10) then sits between coverage and identity, per R11. Both are no-ops when
+        // there is nothing to distinguish (a single required term, or no alternatives supplied).
+        const sortedIds = [...matchMap.entries()]
+            .sort((a, b) => a[1].rank - b[1].rank ||
+            Number(b[1].boosted) - Number(a[1].boosted) ||
+            b[1].coverage - a[1].coverage ||
+            a[1].proximity - b[1].proximity ||
+            a[0] - b[0])
+            .map(([id]) => id);
+        // Build SQL to fetch matched elements with filters
+        let filterClauses = "";
+        const filterParams = [];
+        if (objectType) {
+            filterClauses += " AND o.Object_Type = ?";
+            filterParams.push(objectType);
+        }
+        if (stereotype) {
+            filterClauses += " AND o.Stereotype = ?";
+            filterParams.push(stereotype);
+        }
+        // Fetch all matching elements and apply filters
+        const placeholders = sortedIds.map(() => "?").join(",");
+        const sql = `
+      SELECT o.Object_ID, o.Object_Type, o.Name, o.Alias, o.Stereotype,
+             o.Package_ID, p.Name as PackageName, o.Note
+      FROM t_object o
+      LEFT JOIN t_package p ON o.Package_ID = p.Package_ID
+      WHERE o.Object_ID IN (${placeholders})${filterClauses}
+    `;
+        const allRows = db.prepare(sql).all(...sortedIds, ...filterParams);
+        // Package_ID is on every fetched row, so scoping is a subtree membership check, not a query change.
+        const scopedRows = subtree ? allRows.filter((r) => subtree.has(r.Package_ID)) : allRows;
+        // IN (...) returns rows in whatever order the plan produces, so rank order is restored here.
+        const rowMap = new Map(scopedRows.map((r) => [r.Object_ID, r]));
+        const totalMatched = sortedIds.filter((id) => rowMap.has(id)).length;
+        const sorted = sortedIds
+            .filter((id) => rowMap.has(id))
+            .map((id) => rowMap.get(id));
+        const window = sorted.slice(offset, offset + limit);
+        const truncated = isTruncated(offset, window.length, totalMatched);
+        const evidence = collectEvidence(db, entries, rowMap, new Set(window.map((r) => r.Object_ID)), foldedTerms);
+        const results = window.map((r) => {
+            const decodedNote = decodeEntities(r.Note);
+            const matchedIn = matchMap.get(r.Object_ID)?.matchedIn ?? null;
+            // Previewing from the start hides the reason for a match that lies deeper in the note.
+            // matchedIn is only "t_object.Note" when the note itself carried every required term
+            // (matchObject's single-field branch), so centring on the first term is always valid here.
+            const notePreview = !decodedNote
+                ? null
+                : matchedIn === "t_object.Note"
+                    ? excerptAround(decodedNote, foldText(decodedNote), foldedTerms[0], NOTE_PREVIEW_CHARS).text
+                    : decodedNote.slice(0, NOTE_PREVIEW_CHARS);
+            const notePreviewTruncated = decodedNote != null && decodedNote.length > NOTE_PREVIEW_CHARS;
+            const matches = evidence.get(r.Object_ID);
+            return {
+                Object_ID: r.Object_ID,
+                Object_Type: r.Object_Type,
+                Name: r.Name,
+                Alias: r.Alias,
+                Stereotype: r.Stereotype,
+                Package_ID: r.Package_ID,
+                PackageName: r.PackageName,
+                NotePreview: notePreview,
+                notePreviewTruncated,
+                matchedIn,
+                matches: matches?.items ?? [],
+                _meta: {
+                    matches: {
+                        totalMatched: matches?.totalMatched ?? 0,
+                        returned: matches?.items.length ?? 0,
+                        truncated: (matches?.totalMatched ?? 0) > (matches?.items.length ?? 0),
+                    },
+                },
+            };
+        });
+        const breakdown = breakdownApplies(totalMatched, limit)
+            ? buildBreakdown({
+                objectType: objectType ? undefined : countBy(sorted, (r) => r.Object_Type),
+                stereotype: stereotype ? undefined : countBy(sorted, (r) => r.Stereotype),
+                packageScope: packageScope !== undefined ? undefined : countBy(sorted, (r) => r.Package_ID),
+            })
+            : undefined;
+        const continuation = buildContinuation(toolName, { requiredTerms, objectType, stereotype, packageScope, limit, [altParamName]: alternatives.length > 0 ? alternatives : undefined }, offset, results.length, totalMatched);
+        const response = {
+            results,
+            totalMatched,
+            returned: results.length,
+            offset,
+            truncated,
+            ...(breakdown ? { breakdown } : {}),
+            ...(continuation ? { continuation } : {}),
+            _meta: { sourceTables: ["t_object", "t_attribute", "t_operation", "t_objectconstraint", "t_package"] },
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error searching elements: ${msg}` }],
+            isError: true,
+        };
+    }
+}
+export function configureSearchTools(server, model) {
+    server.tool("ea_search", "Search Enterprise Architect model elements by name, alias, notes, attribute names/notes, operation names/notes, or constraint notes. Matching is case- and diacritic-insensitive across European Latin alphabets and sees through entity-encoded text. `requiredTerms` is a list of terms every one of which must occur somewhere in an element's searchable text (conjunction) — terms need not share a field, but sharing one ranks higher; each term is matched as a contiguous substring exactly as a single term is, so a term carrying whitespace is a phrase and is never split. A one-entry list behaves exactly as a single search term always has. `boostAnyOf` is an optional list of further terms: a result also matching at least one of them ranks ahead of one that does not, but nothing is ever excluded on that basis — for narrowing to only elements matching an alternative too, use `ea_search_and_any_of` instead. When no element matches, `termMatches` reports, per supplied term, whether that term matched anywhere in the corpus at all — so a caller can tell which term emptied the result rather than re-guessing the whole call. Matching elements are returned in `results`, strongest match first, each with a decoded note preview and a truncation flag; equally strong matches fall back to the model's internal identity, a stable but artificial order. Each result also carries `matches`, the evidence for why it was returned: the field that matched, the id and name of the attribute, operation or constraint it came from, and a snippet of the author's own text around the match. Evidence is strongest-first and capped, and `_meta.matches` on the result reports how many matches were found and how many were withheld. The note preview centres on the match when the element's own note is what matched. `packageScope` restricts results to a package (given as its id or its name) and its descendants. Walk a large result set with `offset` rather than a larger `limit`; while rows remain, `continuation` names the next call. When far more elements match than one window can hold, `breakdown` reports how they distribute — by `objectType`, `stereotype`, or, unless already scoped, by `packageScope` (reported as the matching package's id, which the next call can pass straight back) — so the next call can narrow instead of paging.", {
+        requiredTerms: REQUIRED_TERMS_PARAM,
+        boostAnyOf: z
+            .array(z.string())
+            .max(10)
+            .optional()
+            .describe("Terms that promote a result's rank when also present; never excludes. Use ea_search_and_any_of to narrow instead."),
+        objectType: OBJECT_TYPE_PARAM,
+        stereotype: STEREOTYPE_PARAM,
+        packageScope: PACKAGE_SCOPE_PARAM,
+        limit: limitParam(25),
+        offset: offsetParam,
+    }, READ_ONLY, async ({ requiredTerms, boostAnyOf, objectType, stereotype, packageScope, limit, offset }) => {
+        const db = await model.database();
+        return runSearch(db, "ea_search", "boostAnyOf", "boost", { requiredTerms, objectType, stereotype, packageScope, limit, offset }, boostAnyOf ?? []);
+    });
+    server.tool("ea_search_and_any_of", "Search Enterprise Architect model elements the same way `ea_search` does, plus `andAnyOf`: a required-and-alternative filter. `requiredTerms` still works exactly as it does on `ea_search` (conjunction, contiguous substring, terms need not share a field). `andAnyOf` is an optional list of further terms; when supplied, a result must contain `requiredTerms` AND at least one `andAnyOf` term, so it can only ever narrow — it never returns a result `requiredTerms` alone would not. An empty `andAnyOf` array applies no filter. For promoting rather than narrowing, use `ea_search` instead, which offers the same alternatives idea as a rank boost. When no element matches the required terms at all, `termMatches` reports, per supplied term, whether it matched anywhere in the corpus. Matching elements are returned in `results`, strongest first, each with a decoded note preview, a truncation flag, and `matches` — the evidence for why it was returned, capped and strongest-first, with `_meta.matches` reporting how many were found and withheld. `packageScope` restricts results to a package and its descendants. Walk a large result set with `offset`; while rows remain, `continuation` names the next call. When far more elements match than one window can hold, `breakdown` reports how they distribute by `objectType`, `stereotype`, or `packageScope`.", {
+        requiredTerms: REQUIRED_TERMS_PARAM,
+        andAnyOf: z
+            .array(z.string())
+            .max(10)
+            .optional()
+            .describe("Terms a result must also contain at least one of, in addition to requiredTerms; never adds results. Use ea_search's boostAnyOf to only reorder instead."),
+        objectType: OBJECT_TYPE_PARAM,
+        stereotype: STEREOTYPE_PARAM,
+        packageScope: PACKAGE_SCOPE_PARAM,
+        limit: limitParam(25),
+        offset: offsetParam,
+    }, READ_ONLY, async ({ requiredTerms, andAnyOf, objectType, stereotype, packageScope, limit, offset }) => {
+        const db = await model.database();
+        return runSearch(db, "ea_search_and_any_of", "andAnyOf", "filter", { requiredTerms, objectType, stereotype, packageScope, limit, offset }, andAnyOf ?? []);
     });
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const packageVersion = "2.3.0+gf6910be";
+export declare const packageVersion = "3.0.0+gf2d8478";

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "2.3.0+gf6910be";
+export const packageVersion = "3.0.0+gf2d8478";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enterprise-architect-mcp",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "mcpName": "io.github.mm6502/enterprise-architect-mcp",
   "description": "MCP server for read-only access to Sparx Enterprise Architect .qea exports — search elements, navigate packages, read use case scenarios and traverse connectors from an AI agent",
   "keywords": [