enterprise-architect-mcp 2.1.0

package/dist/tools/search.js

@@ -0,0 +1,217 @@
+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";
+const corpora = new WeakMap();
+/** 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)) {
+        if (!/[\p{L}\p{N}]/u.test(text[idx - 1]))
+            return true;
+    }
+    return false;
+}
+/**
+ * The ladder is injective on (sourceTable, sourceField) above rank 3, and ranks 0-3 all
+ * resolve to t_object.Name. That is what makes `matchedIn` independent of corpus scan
+ * order — collapsing any two of these ranks would put an unordered SELECT back in charge
+ * of the answer. Coverage refines name and alias hits, where a query filling more of the
+ * text is a stronger match; for notes it would only measure document length.
+ */
+function scoreMatch(entry, foldedQuery) {
+    const text = entry.foldedText;
+    const coverage = text.length > 0 ? foldedQuery.length / text.length : 0;
+    if (entry.sourceTable === "t_object") {
+        if (entry.sourceField === "Name") {
+            if (text === foldedQuery)
+                return { rank: 0, coverage: 1 };
+            if (text.startsWith(foldedQuery))
+                return { rank: 1, coverage };
+            if (startsAtWordBoundary(text, foldedQuery))
+                return { rank: 2, coverage };
+            return { rank: 3, coverage };
+        }
+        if (entry.sourceField === "Alias")
+            return { rank: 4, coverage };
+        return { rank: 5, coverage: 0 };
+    }
+    if (entry.sourceTable === "t_attribute")
+        return { rank: entry.sourceField === "Name" ? 6 : 8, coverage: 0 };
+    if (entry.sourceTable === "t_operation")
+        return { rank: entry.sourceField === "Name" ? 7 : 9, coverage: 0 };
+    return { rank: 10, coverage: 0 };
+}
+function buildCorpus(db) {
+    const cached = corpora.get(db);
+    if (cached)
+        return cached;
+    const entries = [];
+    // t_object: Name, Alias, Note
+    const objects = db.prepare("SELECT Object_ID, Name, Alias, Note FROM t_object").all();
+    for (const o of objects) {
+        if (o.Name)
+            entries.push({ sourceTable: "t_object", sourceId: o.Object_ID, sourceField: "Name", objectId: o.Object_ID, foldedText: foldText(decodeEntities(o.Name)) });
+        if (o.Alias)
+            entries.push({ sourceTable: "t_object", sourceId: o.Object_ID, sourceField: "Alias", objectId: o.Object_ID, foldedText: foldText(decodeEntities(o.Alias)) });
+        if (o.Note)
+            entries.push({ sourceTable: "t_object", sourceId: o.Object_ID, sourceField: "Note", objectId: o.Object_ID, foldedText: foldText(decodeEntities(o.Note)) });
+    }
+    // t_attribute: Name, Notes
+    const attrs = db.prepare("SELECT ID, Object_ID, Name, Notes FROM t_attribute").all();
+    for (const a of attrs) {
+        if (a.Name)
+            entries.push({ sourceTable: "t_attribute", sourceId: a.ID, sourceField: "Name", objectId: a.Object_ID, foldedText: foldText(decodeEntities(a.Name)) });
+        if (a.Notes)
+            entries.push({ sourceTable: "t_attribute", sourceId: a.ID, sourceField: "Notes", objectId: a.Object_ID, foldedText: foldText(decodeEntities(a.Notes)) });
+    }
+    // t_operation: Name, Notes
+    const ops = db.prepare("SELECT OperationID, Object_ID, Name, Notes FROM t_operation").all();
+    for (const op of ops) {
+        if (op.Name)
+            entries.push({ sourceTable: "t_operation", sourceId: op.OperationID, sourceField: "Name", objectId: op.Object_ID, foldedText: foldText(decodeEntities(op.Name)) });
+        if (op.Notes)
+            entries.push({ sourceTable: "t_operation", sourceId: op.OperationID, sourceField: "Notes", objectId: op.Object_ID, foldedText: foldText(decodeEntities(op.Notes)) });
+    }
+    // t_objectconstraint: Notes
+    const constraints = db.prepare(`SELECT Object_ID, Notes FROM t_objectconstraint WHERE Notes IS NOT NULL AND Notes != ''`).all();
+    for (const c of constraints) {
+        entries.push({ sourceTable: "t_objectconstraint", sourceId: c.Object_ID, sourceField: "Notes", objectId: c.Object_ID, foldedText: foldText(decodeEntities(c.Notes)) });
+    }
+    corpora.set(db, entries);
+    return entries;
+}
+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.", {
+        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"),
+        limit: limitParam(25),
+        offset: offsetParam,
+    }, READ_ONLY, async ({ query, objectType, stereotype, limit, offset }) => {
+        const db = await model.database();
+        try {
+            const entries = buildCorpus(db);
+            const foldedQuery = foldText(query).trim();
+            if (foldedQuery.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: "Query is empty after normalization.",
+                            }, null, 2) }],
+                };
+            }
+            // 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) {
+                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),
+                        }],
+                };
+            }
+            // 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);
+            // 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 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 results = window.map((r) => {
+                const decodedNote = decodeEntities(r.Note);
+                const notePreview = decodedNote ? decodedNote.slice(0, 200) : null;
+                const notePreviewTruncated = decodedNote != null && decodedNote.length > 200;
+                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: matchMap.get(r.Object_ID)?.matchedIn ?? null,
+                };
+            });
+            const breakdown = breakdownApplies(totalMatched, limit)
+                ? buildBreakdown({
+                    objectType: objectType ? undefined : countBy(sorted, (r) => r.Object_Type),
+                    stereotype: stereotype ? undefined : countBy(sorted, (r) => r.Stereotype),
+                })
+                : undefined;
+            const continuation = buildContinuation("ea_search", { query, objectType, stereotype, 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"] },
+            };
+            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,
+            };
+        }
+    });
+}

package/dist/tools/windowing.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+/**
+ * A result set worth more than this many windows cannot be usefully paged through,
+ * so the response describes its shape instead of only sampling it.
+ */
+export declare const BREAKDOWN_LIMIT_FACTOR = 10;
+export declare const offsetParam: z.ZodDefault<z.ZodNumber>;
+/**
+ * A window of zero or fewer rows cannot advance, so a continuation built from it would
+ * repeat the same call forever — and a negative LIMIT makes SQLite return every row.
+ */
+export declare const limitParam: (fallback: number) => z.ZodDefault<z.ZodNumber>;
+export declare function isTruncated(offset: number, returned: number, totalMatched: number): boolean;
+export declare function buildContinuation<T extends Record<string, unknown>>(tool: string, args: T, offset: number, returned: number, totalMatched: number): {
+    tool: string;
+    arguments: T & {
+        offset: number;
+    };
+} | undefined;
+export declare function breakdownApplies(totalMatched: number, limit: number): boolean;
+export interface BreakdownAxis {
+    values: {
+        value: string;
+        count: number;
+    }[];
+    totalMatched: number;
+    returned: number;
+    truncated: boolean;
+}
+export declare function buildAxis(counts: Map<string, number>): BreakdownAxis | undefined;
+/** Tallies a filterable column, skipping blanks: a blank is not an argument a caller can pass back. */
+export declare function countBy<T>(rows: T[], pick: (row: T) => unknown): Map<string, number>;
+/**
+ * Assembles the axes a tool offers, keyed by the parameter name each one narrows.
+ * An axis passed as undefined is one whose filter the caller already supplied.
+ */
+export declare function buildBreakdown(axes: Record<string, Map<string, number> | undefined>): Record<string, BreakdownAxis> | undefined;

package/dist/tools/windowing.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { foldText } from "../text.js";
+/**
+ * A result set worth more than this many windows cannot be usefully paged through,
+ * so the response describes its shape instead of only sampling it.
+ */
+export const BREAKDOWN_LIMIT_FACTOR = 10;
+const MAX_BREAKDOWN_VALUES = 20;
+export const offsetParam = z.coerce
+    .number()
+    .int()
+    .min(0)
+    .default(0)
+    .describe("Zero-based index of the first result to return (default 0). Page by re-calling with the offset carried in continuation.");
+/**
+ * A window of zero or fewer rows cannot advance, so a continuation built from it would
+ * repeat the same call forever — and a negative LIMIT makes SQLite return every row.
+ */
+export const limitParam = (fallback) => z.coerce
+    .number()
+    .int()
+    .min(1)
+    .default(fallback)
+    .describe(`Maximum number of results to return (default ${fallback})`);
+export function isTruncated(offset, returned, totalMatched) {
+    return offset + returned < totalMatched;
+}
+export function buildContinuation(tool, args, offset, returned, totalMatched) {
+    if (!isTruncated(offset, returned, totalMatched))
+        return undefined;
+    return { tool, arguments: { ...args, offset: offset + returned } };
+}
+export function breakdownApplies(totalMatched, limit) {
+    return totalMatched > BREAKDOWN_LIMIT_FACTOR * limit;
+}
+/**
+ * Counts in, one breakdown axis out. Axis extraction stays with the tool, because
+ * only the tool knows which of its parameters a column corresponds to.
+ */
+/**
+ * The cap below makes the value list a truncated window, and under binary order every
+ * accented value sorts past every plain one — so a tie at the cap would drop the
+ * accented value every time. Folding first is locale-independent, unlike compareNames,
+ * which matters because these values come back as filter arguments.
+ */
+function compareValues(a, b) {
+    const foldedA = foldText(a);
+    const foldedB = foldText(b);
+    if (foldedA !== foldedB)
+        return foldedA < foldedB ? -1 : 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function buildAxis(counts) {
+    // One value only restates a filter the caller could already have applied.
+    if (counts.size < 2)
+        return undefined;
+    const sorted = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || compareValues(a[0], b[0]))
+        .map(([value, count]) => ({ value, count }));
+    const values = sorted.slice(0, MAX_BREAKDOWN_VALUES);
+    return {
+        values,
+        totalMatched: sorted.length,
+        returned: values.length,
+        truncated: sorted.length > values.length,
+    };
+}
+/** Tallies a filterable column, skipping blanks: a blank is not an argument a caller can pass back. */
+export function countBy(rows, pick) {
+    const counts = new Map();
+    for (const row of rows) {
+        const raw = pick(row);
+        if (raw == null || raw === "")
+            continue;
+        const key = String(raw);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return counts;
+}
+/**
+ * Assembles the axes a tool offers, keyed by the parameter name each one narrows.
+ * An axis passed as undefined is one whose filter the caller already supplied.
+ */
+export function buildBreakdown(axes) {
+    const built = {};
+    for (const [parameter, counts] of Object.entries(axes)) {
+        const axis = counts && buildAxis(counts);
+        if (axis)
+            built[parameter] = axis;
+    }
+    return Object.keys(built).length > 0 ? built : undefined;
+}

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ModelAccess } from "./model-session.js";
+export declare function configureAllTools(server: McpServer, model: ModelAccess): void;

package/dist/tools.js

@@ -0,0 +1,18 @@
+import { configureSearchTools } from "./tools/search.js";
+import { configureElementTools } from "./tools/elements.js";
+import { configureConnectorTools } from "./tools/connectors.js";
+import { configurePackageTools } from "./tools/packages.js";
+import { configureDiagramTools } from "./tools/diagrams.js";
+import { configureScenarioTools } from "./tools/scenarios.js";
+import { configureSchemaTools } from "./tools/schema.js";
+import { configureResolveTools } from "./tools/resolve.js";
+export function configureAllTools(server, model) {
+    configureSearchTools(server, model);
+    configureElementTools(server, model);
+    configureConnectorTools(server, model);
+    configurePackageTools(server, model);
+    configureDiagramTools(server, model);
+    configureScenarioTools(server, model);
+    configureSchemaTools(server, model);
+    configureResolveTools(server, model);
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const packageVersion = "2.1.0+20260828043121";

package/dist/version.js

@@ -0,0 +1 @@
+export const packageVersion = "2.1.0+20260828043121";

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "enterprise-architect-mcp",
+  "version": "2.1.0",
+  "mcpName": "io.github.mm6502/enterprise-architect-mcp",
+  "description": "MCP server for read-only access to Sparx Enterprise Architect .qea exports \u2014 search elements, navigate packages, read use case scenarios and traverse connectors from an AI agent",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "enterprise-architect",
+    "sparx",
+    "sparx-ea",
+    "qea",
+    "uml",
+    "use-case",
+    "architecture",
+    "ai-agents",
+    "llm-tools",
+    "claude",
+    "sqlite",
+    "typescript"
+  ],
+  "homepage": "https://github.com/mm6502/enterprise-architect-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mm6502/enterprise-architect-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mm6502/enterprise-architect-mcp/issues"
+  },
+  "license": "EUPL-1.2",
+  "author": "Michal Mracka",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "mcp-server-ea": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "node -e \"const v=require('./package.json').version;const ts=new Date().toISOString().replace(/[-:T]/g,'').slice(0,14);require('fs').writeFileSync('src/version.ts','export const packageVersion = '+JSON.stringify(v+'+'+ts)+';\\n')\"",
+    "build": "tsc",
+    "precommit": "npm run build",
+    "prepublishOnly": "npm run build && npm test",
+    "watch": "tsc --watch",
+    "test": "jest",
+    "eval:run": "npx tsx eval/runner.ts",
+    "eval:model": "npx tsx eval/build-model.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "fast-xml-parser": "^5.10.1",
+    "yargs": "^17.7.2",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.15.31",
+    "@types/yargs": "^17.0.33",
+    "jest": "^29.7.0",
+    "shx": "^0.3.4",
+    "ts-jest": "^29.3.4",
+    "typescript": "^5.8.3"
+  }
+}