enterprise-architect-mcp 2.2.0 → 2.3.0

package/README.md

@@ -102,7 +102,7 @@ takes the first source that actually opens:
 
 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 `ignored`. That is deliberate — a sample value left in an `env` block would otherwise
+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.
@@ -148,8 +148,9 @@ 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`, or `diagramType` — rather than to page through
-thousands of rows.
+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
 
@@ -180,12 +181,12 @@ hand; answering the prompt once is what makes that unnecessary.
 
 | 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. |
+| `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_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_scenarios` | Use case scenario steps with all attributes (trigger, uses, result, link, state) and scenario notes. |
+| `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. |
 | `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`. |

package/dist/package-path.d.ts

@@ -1,2 +1,18 @@
 import type { Database } from "./database.js";
 export declare function buildPackagePath(db: Database, packageId: number): string;
+/** The scope package plus every descendant, walked down the same hierarchy buildPackagePath walks up. */
+export declare function getPackageSubtree(db: Database, rootId: number): Set<number>;
+export type PackageScopeResolution = {
+    kind: "found";
+    packageId: number;
+} | {
+    kind: "not_found";
+} | {
+    kind: "ambiguous";
+    candidates: {
+        id: number;
+        fullPackagePath: string;
+    }[];
+};
+/** Resolves a package id or name to a single package, the way ea_resolve resolves a name to a candidate. */
+export declare function resolvePackageScope(db: Database, scope: number | string): PackageScopeResolution;

package/dist/package-path.js

@@ -1,8 +1,10 @@
+import { foldText } from "./text.js";
 /**
  * Build the full package path from root to the given package, dot-separated.
  * Uses a preloaded package map memoized per database connection.
  */
 const packageMaps = new WeakMap();
+const childrenMaps = new WeakMap();
 function getPackageMap(db) {
     let map = packageMaps.get(db);
     if (map)
@@ -17,6 +19,22 @@ function getPackageMap(db) {
     packageMaps.set(db, map);
     return map;
 }
+/** Parent-to-children index, built once from the same map buildPackagePath reads upward. */
+function getChildrenMap(db) {
+    let map = childrenMaps.get(db);
+    if (map)
+        return map;
+    map = new Map();
+    for (const [id, pkg] of getPackageMap(db)) {
+        const siblings = map.get(pkg.parentId);
+        if (siblings)
+            siblings.push(id);
+        else
+            map.set(pkg.parentId, [id]);
+    }
+    childrenMaps.set(db, map);
+    return map;
+}
 export function buildPackagePath(db, packageId) {
     const map = getPackageMap(db);
     const parts = [];
@@ -34,3 +52,37 @@ export function buildPackagePath(db, packageId) {
     }
     return parts.join(".");
 }
+/** The scope package plus every descendant, walked down the same hierarchy buildPackagePath walks up. */
+export function getPackageSubtree(db, rootId) {
+    const children = getChildrenMap(db);
+    const result = new Set([rootId]);
+    const stack = [rootId];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        for (const child of children.get(current) ?? []) {
+            if (!result.has(child)) {
+                result.add(child);
+                stack.push(child);
+            }
+        }
+    }
+    return result;
+}
+/** Resolves a package id or name to a single package, the way ea_resolve resolves a name to a candidate. */
+export function resolvePackageScope(db, scope) {
+    const map = getPackageMap(db);
+    if (typeof scope === "number") {
+        return map.has(scope) ? { kind: "found", packageId: scope } : { kind: "not_found" };
+    }
+    const folded = foldText(scope);
+    const matches = [];
+    for (const [id, pkg] of map) {
+        if (foldText(pkg.name) === folded)
+            matches.push(id);
+    }
+    if (matches.length === 0)
+        return { kind: "not_found" };
+    if (matches.length === 1)
+        return { kind: "found", packageId: matches[0] };
+    return { kind: "ambiguous", candidates: matches.map((id) => ({ id, fullPackagePath: buildPackagePath(db, id) })) };
+}

package/dist/tools/scenarios.js

@@ -38,7 +38,7 @@ const SCENARIO_TYPE_ORDER = {
     "Exception": 2,
 };
 export function configureScenarioTools(server, model) {
-    server.tool("ea_get_scenarios", "Get use case scenario flows for an element. `scenarios` holds the parsed flows; each has `name`, `type`, `notes`, and `steps`, and each step carries `stepNumber` plus its attributes (`trigger`, `uses`, `result`, `state`, `link`). Steps are numbered within each scenario. Scenarios ordered by type: Basic Path first, then Alternate, then Exception.", {
+    server.tool("ea_get_scenarios", "Get use case scenario flows for an element. `scenarios` holds the parsed flows; each has `name`, `type`, `notes`, and `steps`, and each step carries `stepNumber` plus its attributes (`trigger`, `uses`, `result`, `state`, `link`). Steps are numbered within each scenario. Scenarios ordered by type: Basic Path first, then Alternate, then Exception. A step's `uses` may name a business rule or constraint by code; that code is not independently searchable or resolvable — look it up among this same elementId's own constraints via `ea_get_element`, not by a separate lookup.", {
         elementId: z.coerce.number().describe("The Object_ID of the element (typically a UseCase) to get scenarios for"),
     }, READ_ONLY, async ({ elementId }) => {
         const db = await model.database();

package/dist/tools/search.js

@@ -2,7 +2,53 @@ import { READ_ONLY } from "./annotations.js";
 import { z } from "zod";
 import { decodeEntities, foldText } from "../text.js";
 import { breakdownApplies, buildBreakdown, buildContinuation, countBy, isTruncated, limitParam, offsetParam } from "./windowing.js";
+import { getPackageSubtree, resolvePackageScope } from "../package-path.js";
 const corpora = new WeakMap();
+const MAX_INLINE_MATCHES = 3;
+const SNIPPET_CHARS = 150;
+const NOTE_PREVIEW_CHARS = 200;
+function wordSpans(s) {
+    const spans = [];
+    const re = /\S+/g;
+    for (let m = re.exec(s); m !== null; m = re.exec(s))
+        spans.push([m.index, m.index + m[0].length]);
+    return spans;
+}
+/**
+ * No step in foldText creates or removes whitespace, so the k-th word of the folded text
+ * is the k-th word of the original. That is what locates a match in the author's own text
+ * without keeping an offset map between the two forms.
+ */
+function excerptAround(original, folded, foldedQuery, budget) {
+    const at = folded.indexOf(foldedQuery);
+    const foldedWords = wordSpans(folded);
+    const words = wordSpans(original);
+    // A word that folds away entirely would break the correspondence; fall back rather than misquote.
+    if (at < 0 || foldedWords.length !== words.length || words.length === 0) {
+        return { text: original.slice(0, budget), truncated: original.length > budget };
+    }
+    const end = at + foldedQuery.length;
+    let lo = foldedWords.findIndex(([, e]) => e > at);
+    if (lo < 0)
+        lo = 0;
+    let hi = lo;
+    while (hi + 1 < foldedWords.length && foldedWords[hi + 1][0] < end)
+        hi++;
+    for (let grew = true; grew;) {
+        grew = false;
+        if (lo > 0 && words[hi][1] - words[lo - 1][0] <= budget) {
+            lo--;
+            grew = true;
+        }
+        if (hi + 1 < words.length && words[hi + 1][1] - words[lo][0] <= budget) {
+            hi++;
+            grew = true;
+        }
+    }
+    const head = lo > 0 ? "…" : "";
+    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. */
 function startsAtWordBoundary(text, query) {
     for (let idx = text.indexOf(query); idx > 0; idx = text.indexOf(query, idx + 1)) {
@@ -80,19 +126,147 @@ function buildCorpus(db) {
     corpora.set(db, entries);
     return entries;
 }
+function selectIn(db, sql, ids) {
+    if (ids.size === 0)
+        return [];
+    const list = [...ids];
+    return db.prepare(`${sql} (${list.map(() => "?").join(",")})`).all(...list);
+}
+/** The author's own text behind a corpus entry, with the name of whatever carried it. */
+function originalFor(entry, src) {
+    const decoded = (raw, name) => typeof raw === "string" && raw.length > 0 ? { text: decodeEntities(raw), name } : null;
+    if (entry.sourceTable === "t_object") {
+        return decoded(src.rows.get(entry.objectId)?.[entry.sourceField], null);
+    }
+    if (entry.sourceTable === "t_attribute") {
+        const a = src.attributes.get(entry.sourceId);
+        return a ? decoded(entry.sourceField === "Name" ? a.Name : a.Notes, a.Name ?? null) : null;
+    }
+    if (entry.sourceTable === "t_operation") {
+        const op = src.operations.get(entry.sourceId);
+        return op ? decoded(entry.sourceField === "Name" ? op.Name : op.Notes, op.Name ?? null) : null;
+    }
+    if (entry.sourceTable === "t_objectconstraint") {
+        // Constraint rows carry no identity of their own, so the right note is found by its folded form.
+        const row = (src.constraints.get(entry.sourceId) ?? [])
+            .find((c) => typeof c.Notes === "string" && foldText(decodeEntities(c.Notes)) === entry.foldedText);
+        return row ? decoded(row.Notes, row.Constraint ?? null) : null;
+    }
+    return null;
+}
+/**
+ * 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.
+ */
+function collectEvidence(db, entries, rows, windowIds, foldedQuery) {
+    const hits = new Map();
+    for (const entry of entries) {
+        if (!windowIds.has(entry.objectId) || !entry.foldedText.includes(foldedQuery))
+            continue;
+        const list = hits.get(entry.objectId);
+        if (list)
+            list.push(entry);
+        else
+            hits.set(entry.objectId, [entry]);
+    }
+    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)
+            .slice(0, MAX_INLINE_MATCHES)
+            .map((r) => r.e);
+        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) {
+            if (e.sourceTable === "t_attribute")
+                attributeIds.add(e.sourceId);
+            else if (e.sourceTable === "t_operation")
+                operationIds.add(e.sourceId);
+            else if (e.sourceTable === "t_objectconstraint")
+                constraintOwners.add(e.sourceId);
+        }
+    }
+    const constraints = new Map();
+    for (const c of selectIn(db, `SELECT Object_ID, "Constraint", Notes FROM t_objectconstraint WHERE Object_ID IN`, constraintOwners)) {
+        const list = constraints.get(c.Object_ID);
+        if (list)
+            list.push(c);
+        else
+            constraints.set(c.Object_ID, [c]);
+    }
+    const src = {
+        rows,
+        attributes: new Map(selectIn(db, "SELECT ID, Name, Notes FROM t_attribute WHERE ID IN", attributeIds).map((a) => [a.ID, a])),
+        operations: new Map(selectIn(db, "SELECT OperationID, Name, Notes FROM t_operation WHERE OperationID IN", operationIds).map((o) => [o.OperationID, o])),
+        constraints,
+    };
+    const evidence = new Map();
+    for (const [objectId, { entries: shown, totalMatched }] of kept) {
+        const items = [];
+        for (const entry of shown) {
+            const original = originalFor(entry, src);
+            if (!original)
+                continue;
+            const excerpt = excerptAround(original.text, entry.foldedText, foldedQuery, SNIPPET_CHARS);
+            items.push({
+                matchedIn: `${entry.sourceTable}.${entry.sourceField}`,
+                sourceId: entry.sourceId,
+                sourceName: original.name,
+                snippet: excerpt.text,
+                snippetTruncated: excerpt.truncated,
+            });
+        }
+        evidence.set(objectId, { items, totalMatched });
+    }
+    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. 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, so the next call can narrow by `objectType` or `stereotype` instead of paging.", {
+    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, limit, offset }) => {
+    }, 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) {
@@ -160,18 +334,28 @@ export function configureSearchTools(server, model) {
           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(allRows.map((r) => [r.Object_ID, r]));
+            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 notePreview = decodedNote ? decodedNote.slice(0, 200) : null;
-                const notePreviewTruncated = decodedNote != null && decodedNote.length > 200;
+                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,
@@ -182,16 +366,25 @@ export function configureSearchTools(server, model) {
                     PackageName: r.PackageName,
                     NotePreview: notePreview,
                     notePreviewTruncated,
-                    matchedIn: matchMap.get(r.Object_ID)?.matchedIn ?? null,
+                    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, limit }, offset, results.length, totalMatched);
+            const continuation = buildContinuation("ea_search", { query, objectType, stereotype, packageScope, limit }, offset, results.length, totalMatched);
             const response = {
                 results,
                 totalMatched,

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const packageVersion = "2.2.0+g9b1dad6";
+export declare const packageVersion = "2.3.0+gf6910be";

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "2.2.0+g9b1dad6";
+export const packageVersion = "2.3.0+gf6910be";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enterprise-architect-mcp",
-  "version": "2.2.0",
+  "version": "2.3.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": [
@@ -48,7 +48,8 @@
     "watch": "tsc --watch",
     "test": "jest",
     "eval:run": "tsx eval/runner.ts",
-    "eval:model": "tsx eval/build-model.ts"
+    "eval:model": "tsx eval/build-model.ts",
+    "eval:agent": "tsx eval/agent-runner-cli.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",