enterprise-architect-mcp 2.1.0

package/dist/tools/packages.js

@@ -0,0 +1,80 @@
+import { READ_ONLY } from "./annotations.js";
+import { z } from "zod";
+const MAX_PACKAGES = 200;
+export function configurePackageTools(server, model) {
+    server.tool("ea_get_package_tree", "Navigate the package hierarchy. Without parameters, returns top-level `packages`. With a `packageId`, returns that package's children up to the specified depth. Each node carries `id`, `name`, `parentId`, and `elementCount`.", {
+        packageId: z.coerce.number().optional().describe("Package ID to get children of. Omit for top-level packages."),
+        depth: z.coerce.number().default(1).describe("How many levels deep to recurse (max 3, default 1)"),
+    }, READ_ONLY, async ({ packageId, depth }) => {
+        const db = await model.database();
+        try {
+            const effectiveDepth = Math.min(depth, 3);
+            const parentId = packageId ?? 0;
+            // Verify package exists when a specific ID is requested
+            if (packageId != null && packageId !== 0) {
+                const pkgExists = db.prepare("SELECT Package_ID FROM t_package WHERE Package_ID = ?").get(packageId);
+                if (!pkgExists) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ error: "not_found", message: `Package with ID ${packageId} not found`, packageId }, null, 2) }],
+                        isError: true,
+                    };
+                }
+            }
+            let totalCount = 0;
+            function getChildren(pid, currentDepth) {
+                if (currentDepth <= 0 || totalCount >= MAX_PACKAGES)
+                    return [];
+                const packages = db.prepare(`
+            SELECT p.Package_ID, p.Name, p.Parent_ID
+            FROM t_package p
+            WHERE p.Parent_ID = ?
+            ORDER BY p.TPos, p.Name
+          `).all(pid);
+                const result = [];
+                for (const pkg of packages) {
+                    if (totalCount >= MAX_PACKAGES)
+                        break;
+                    totalCount++;
+                    const countRow = db.prepare("SELECT COUNT(*) as cnt FROM t_object WHERE Package_ID = ?").get(pkg.Package_ID);
+                    const node = {
+                        id: pkg.Package_ID,
+                        name: pkg.Name,
+                        parentId: pkg.Parent_ID,
+                        elementCount: countRow.cnt,
+                    };
+                    if (currentDepth > 1) {
+                        const children = getChildren(pkg.Package_ID, currentDepth - 1);
+                        if (children.length > 0) {
+                            node.children = children;
+                        }
+                    }
+                    result.push(node);
+                }
+                return result;
+            }
+            const tree = getChildren(parentId, effectiveDepth);
+            const truncated = totalCount >= MAX_PACKAGES;
+            const response = {
+                packages: tree,
+                totalMatched: totalCount,
+                returned: tree.length,
+                truncated,
+                _meta: { sourceTables: ["t_package", "t_object"] },
+            };
+            if (truncated) {
+                response.message = `Results truncated at ${MAX_PACKAGES} packages. Use a specific packageId to drill deeper.`;
+                response.continuation = { tool: "ea_get_package_tree", arguments: { packageId: parentId, depth: effectiveDepth } };
+            }
+            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 retrieving package tree: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/resolve.d.ts

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

package/dist/tools/resolve.js

@@ -0,0 +1,135 @@
+import { READ_ONLY } from "./annotations.js";
+import { z } from "zod";
+import { buildPackagePath } from "../package-path.js";
+import { foldText } from "../text.js";
+function isBracedGuid(ref) {
+    return /^\{[^}]+\}$/.test(ref.trim());
+}
+function resolveByGuid(db, guid, kind) {
+    const candidates = [];
+    if (!kind || kind === "element") {
+        const rows = db.prepare("SELECT Object_ID, Object_Type, Name, Package_ID, ea_guid FROM t_object WHERE ea_guid = ? COLLATE NOCASE").all(guid);
+        for (const r of rows) {
+            candidates.push({
+                type: "element", id: r.Object_ID, name: r.Name,
+                match: "guid",
+                fullPackagePath: buildPackagePath(db, r.Package_ID),
+                eaGuid: r.ea_guid, objectType: r.Object_Type,
+            });
+        }
+    }
+    if (!kind || kind === "diagram") {
+        const rows = db.prepare("SELECT Diagram_ID, Name, Package_ID, ea_guid FROM t_diagram WHERE ea_guid = ? COLLATE NOCASE").all(guid);
+        for (const r of rows) {
+            candidates.push({
+                type: "diagram", id: r.Diagram_ID, name: r.Name,
+                match: "guid",
+                fullPackagePath: buildPackagePath(db, r.Package_ID),
+                eaGuid: r.ea_guid,
+            });
+        }
+    }
+    if (!kind || kind === "package") {
+        const rows = db.prepare("SELECT Package_ID, Name, Parent_ID, ea_guid FROM t_package WHERE ea_guid = ? COLLATE NOCASE").all(guid);
+        for (const r of rows) {
+            candidates.push({
+                type: "package", id: r.Package_ID, name: r.Name,
+                match: "guid",
+                fullPackagePath: buildPackagePath(db, r.Package_ID),
+                eaGuid: r.ea_guid,
+            });
+        }
+    }
+    return candidates;
+}
+function resolveByName(db, name, kind) {
+    const folded = foldText(name);
+    const prefix = `${folded}:`;
+    const exactCandidates = [];
+    const prefixCandidates = [];
+    const addCandidate = (candidateName, createCandidate) => {
+        const foldedCandidate = foldText(candidateName);
+        const match = foldedCandidate === folded
+            ? "exact"
+            : foldedCandidate.startsWith(prefix)
+                ? "prefix"
+                : undefined;
+        if (match) {
+            (match === "exact" ? exactCandidates : prefixCandidates).push({
+                ...createCandidate(),
+                match,
+            });
+        }
+    };
+    if (!kind || kind === "element") {
+        const rows = db.prepare("SELECT Object_ID, Object_Type, Name, Package_ID, ea_guid FROM t_object").all();
+        for (const r of rows) {
+            addCandidate(r.Name || "", () => ({
+                type: "element", id: r.Object_ID, name: r.Name,
+                fullPackagePath: buildPackagePath(db, r.Package_ID),
+                eaGuid: r.ea_guid, objectType: r.Object_Type,
+            }));
+        }
+    }
+    if (!kind || kind === "diagram") {
+        const rows = db.prepare("SELECT Diagram_ID, Name, Package_ID, ea_guid FROM t_diagram").all();
+        for (const r of rows) {
+            addCandidate(r.Name || "", () => ({
+                type: "diagram", id: r.Diagram_ID, name: r.Name,
+                fullPackagePath: buildPackagePath(db, r.Package_ID),
+                eaGuid: r.ea_guid,
+            }));
+        }
+    }
+    if (!kind || kind === "package") {
+        const rows = db.prepare("SELECT Package_ID, Name, Parent_ID, ea_guid FROM t_package").all();
+        for (const r of rows) {
+            addCandidate(r.Name || "", () => ({
+                type: "package", id: r.Package_ID, name: r.Name,
+                fullPackagePath: buildPackagePath(db, r.Package_ID),
+                eaGuid: r.ea_guid,
+            }));
+        }
+    }
+    return exactCandidates.length > 0 ? exactCandidates : prefixCandidates;
+}
+export function configureResolveTools(server, model) {
+    server.tool("ea_resolve", "Resolve an analyst reference (braced GUID or plain name) to model candidates: the input is echoed as `reference` and the hits are in `candidates`. A braced GUID is matched exactly. A plain name is matched against the full name first; only if nothing matches exactly is the reference retried as a name prefix, which resolves analyst codes like UC_ABC_2079 or OA_ABC_2280 to elements named 'CODE: description'. An exact hit is returned alone and is never diluted by prefix hits. Each candidate reports its `type` (element, diagram, package), `id`, `name`, `fullPackagePath`, `eaGuid`, and a `match` field that is always present with value \"guid\", \"exact\", or \"prefix\" — a \"prefix\" candidate is an inexact match and must not be treated as a confirmed identity. Use the optional `kind` filter to narrow results.", {
+        reference: z.string().describe("The reference to resolve: a braced GUID like {ABC-123} or a plain name"),
+        kind: z
+            .enum(["element", "diagram", "package"])
+            .optional()
+            .describe("Filter candidates to a specific kind"),
+    }, READ_ONLY, async ({ reference, kind }) => {
+        const db = await model.database();
+        try {
+            let candidates;
+            if (isBracedGuid(reference)) {
+                candidates = resolveByGuid(db, reference.trim(), kind);
+            }
+            else {
+                candidates = resolveByName(db, reference.trim(), kind);
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            reference,
+                            candidates,
+                            totalMatched: candidates.length,
+                            returned: candidates.length,
+                            truncated: false,
+                            _meta: { sourceTables: ["t_object", "t_diagram", "t_package"] },
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: "text", text: `Error resolving reference: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/scenarios.d.ts

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

package/dist/tools/scenarios.js

@@ -0,0 +1,106 @@
+import { READ_ONLY } from "./annotations.js";
+import { z } from "zod";
+import { XMLParser } from "fast-xml-parser";
+import { decodeEntities, compareNames } from "../text.js";
+const xmlParser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    isArray: (name) => name === "step",
+});
+function parseScenarioXml(xml) {
+    if (!xml || xml.trim() === "")
+        return [];
+    try {
+        const parsed = xmlParser.parse(xml);
+        const steps = parsed?.path?.step;
+        if (!steps)
+            return [];
+        return (Array.isArray(steps) ? steps : [steps]).map((s) => ({
+            name: s["@_name"] || "",
+            level: parseInt(s["@_level"] || "0", 10),
+            guid: s["@_guid"] || "",
+            trigger: s["@_trigger"] || null,
+            uses: s["@_uses"] || null,
+            useslist: s["@_useslist"] || null,
+            result: s["@_result"] || null,
+            state: s["@_state"] || null,
+            link: s["@_link"] || null,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+// R9: Scenario type ordering — Basic Path first, then Alternate, then Exception
+const SCENARIO_TYPE_ORDER = {
+    "Basic Path": 0,
+    "Alternate": 1,
+    "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.", {
+        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();
+        try {
+            // Verify element exists
+            const elExists = db.prepare("SELECT Object_ID FROM t_object WHERE Object_ID = ?").get(elementId);
+            if (!elExists) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: "not_found", message: `Element with ID ${elementId} not found`, elementId }, null, 2) }],
+                    isError: true,
+                };
+            }
+            const rows = db.prepare(`
+          SELECT Scenario, ScenarioType, XMLContent, Notes
+          FROM t_objectscenarios
+          WHERE Object_ID = ?
+        `).all(elementId);
+            if (rows.length === 0) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                scenarios: [],
+                                totalMatched: 0,
+                                returned: 0,
+                                truncated: false,
+                                _meta: { sourceTables: ["t_objectscenarios"] },
+                            }, null, 2) }],
+                };
+            }
+            // R9: Sort by scenario type order, then by name within each type
+            rows.sort((a, b) => {
+                const aOrder = SCENARIO_TYPE_ORDER[a.ScenarioType] ?? 99;
+                const bOrder = SCENARIO_TYPE_ORDER[b.ScenarioType] ?? 99;
+                if (aOrder !== bOrder)
+                    return aOrder - bOrder;
+                return compareNames(a.Scenario, b.Scenario);
+            });
+            const scenarios = rows.map((row) => {
+                const rawSteps = parseScenarioXml(row.XMLContent);
+                return {
+                    name: row.Scenario,
+                    type: row.ScenarioType,
+                    notes: decodeEntities(row.Notes),
+                    steps: rawSteps.map((s, i) => ({ stepNumber: i + 1, ...s })),
+                };
+            });
+            const response = {
+                scenarios,
+                totalMatched: scenarios.length,
+                returned: scenarios.length,
+                truncated: false,
+                _meta: { sourceTables: ["t_objectscenarios"] },
+            };
+            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 retrieving scenarios: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/schema.d.ts

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

package/dist/tools/schema.js

@@ -0,0 +1,164 @@
+import { describeSource } from "../model-session.js";
+import { READ_ONLY } from "./annotations.js";
+import { z } from "zod";
+import { statSync } from "node:fs";
+import { packageVersion } from "../version.js";
+export function configureSchemaTools(server, model) {
+    server.tool("ea_get_schema", "List the model's database tables in `tables`, or pass a `tableName` to get that table's `columns` and `indexes` instead. That form echoes the `table` name and adds `rowidAlias` — the INTEGER PRIMARY KEY aliasing SQLite's rowid, so the fastest lookup path, or null when the table has none — with `rowidNote` saying which case applies. Use this to discover what data the model holds beyond what the typed ea_* tools return. See ea_get_model_info for the export's identity.", {
+        tableName: z
+            .string()
+            .optional()
+            .describe("Table name to inspect. Omit to list all tables with row counts."),
+    }, READ_ONLY, async ({ tableName }) => {
+        const db = await model.database();
+        try {
+            if (!tableName) {
+                const tables = db
+                    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name`)
+                    .all();
+                const result = tables.map((t) => {
+                    const row = db.prepare(`SELECT COUNT(*) as cnt FROM "${t.name}"`).get();
+                    return { table: t.name, rowCount: row.cnt };
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                tables: result,
+                                totalMatched: result.length,
+                                returned: result.length,
+                                truncated: false,
+                                _meta: { sourceTables: ["sqlite_master"] },
+                            }, null, 2) }],
+                };
+            }
+            // Verify table exists
+            const exists = db
+                .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+                .get(tableName);
+            if (!exists) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: "not_found", message: `Table '${tableName}' not found`, tableName }, null, 2) }],
+                    isError: true,
+                };
+            }
+            // Columns — tableName is validated against sqlite_master above
+            const safeTableName = exists.name;
+            const columns = db.prepare(`PRAGMA table_info("${safeTableName}")`).all();
+            // Rowid alias detection: exactly one column with pk > 0 and declared type INTEGER (case-insensitive)
+            const pkColumns = columns.filter((c) => c.pk > 0);
+            const rowidAlias = pkColumns.length === 1 && pkColumns[0].type.toUpperCase() === "INTEGER"
+                ? pkColumns[0].name
+                : null;
+            // Indexes
+            const indexList = db.prepare(`PRAGMA index_list("${safeTableName}")`).all();
+            const indexes = indexList.map((idx) => {
+                const indexCols = db.prepare(`PRAGMA index_info("${idx.name}")`).all();
+                return {
+                    name: idx.name,
+                    unique: idx.unique === 1,
+                    columns: indexCols.map((c) => c.name),
+                };
+            });
+            const result = {
+                table: tableName,
+                columns: columns.map((c) => ({
+                    name: c.name,
+                    type: c.type,
+                    notNull: c.notnull === 1,
+                    primaryKey: c.pk > 0,
+                    defaultValue: c.dflt_value,
+                })),
+                indexes,
+                _meta: {
+                    sourceTables: ["sqlite_master"],
+                    columns: { totalMatched: columns.length, returned: columns.length, truncated: false },
+                    indexes: { totalMatched: indexes.length, returned: indexes.length, truncated: false },
+                },
+            };
+            if (rowidAlias) {
+                result.rowidAlias = rowidAlias;
+                result.rowidNote =
+                    "This column is an INTEGER PRIMARY KEY that aliases SQLite's internal rowid. Lookups by this column are the fastest access path.";
+            }
+            else {
+                result.rowidAlias = null;
+                result.rowidNote = "This table has no single-column INTEGER PRIMARY KEY rowid alias.";
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error reading schema: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("ea_get_model_info", "Report which .qea export file the server has open: `fileName` is the citable identity, alongside `fileSizeBytes`, `lastModified`, and the `serverVersion` that produced the answer. The full local path is also returned as `resolvedPath`, with `resolvedPathNote` explaining why it is environment detail rather than something to cite. `configuration` says where that path came from — `source` in words, `sourceId` as one of argument/environment/dotenv/remembered/prompt, and the `configured` value behind it — plus any `skipped` settings, each with the `reason` it could not be opened, and `shadowed` ones a higher-priority source outranked; `configurationNote` says how much of that is safe to repeat.", {}, READ_ONLY, async () => {
+        const db = await model.database();
+        try {
+            const location = db.location();
+            if (!location) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Model info unavailable: database has no file location (in-memory database).",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const stat = statSync(location);
+            const fileName = location.replace(/\\/g, "/").split("/").pop() ?? location;
+            const origin = model.origin();
+            const result = {
+                fileName,
+                fileSizeBytes: stat.size,
+                lastModified: stat.mtime.toISOString(),
+                serverVersion: packageVersion,
+                resolvedPath: location,
+                resolvedPathNote: "The resolved path is local detail — it may contain user-specific directories. Use fileName, size, and lastModified as the citable identity.",
+                ...(origin && {
+                    configuration: {
+                        source: describeSource(origin.source),
+                        sourceId: origin.source,
+                        configured: origin.configured,
+                        skipped: origin.ignored.map((entry) => ({
+                            source: describeSource(entry.source),
+                            sourceId: entry.source,
+                            configured: entry.configured,
+                            reason: entry.reason,
+                        })),
+                        shadowed: origin.shadowed.map((entry) => ({
+                            source: describeSource(entry.source),
+                            sourceId: entry.source,
+                            configured: entry.configured,
+                        })),
+                    },
+                    configurationNote: "Everything under configuration is local environment detail: configured values are filesystem paths and each skipped reason quotes one in full. Repeat them only when explaining a configuration problem to the user who owns the machine, never as model identity.",
+                }),
+                _meta: { sourceTables: [] },
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error reading model info: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/search.d.ts

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