enterprise-architect-mcp 2.1.0

package/dist/tools/connectors.js

@@ -0,0 +1,152 @@
+import { READ_ONLY } from "./annotations.js";
+import { z } from "zod";
+import { decodeEntities } from "../text.js";
+// Extract braced GUID from LFSP/LFEP tokens, discarding trailing anchor letter
+const FEATURE_LINK_RE = /LF([SE])P=\{([^}]+)\}[^;]*/g;
+function resolveFeatureGuid(db, guid) {
+    // Try attribute first
+    const attr = db
+        .prepare(`SELECT a.Name, a.Notes, o.Name as ElementName
+       FROM t_attribute a LEFT JOIN t_object o ON a.Object_ID = o.Object_ID
+       WHERE a.ea_guid = ? COLLATE NOCASE`)
+        .get(guid);
+    if (attr) {
+        return { name: attr.Name, owningElementName: attr.ElementName, notes: decodeEntities(attr.Notes), type: "attribute" };
+    }
+    // Try operation
+    const op = db
+        .prepare(`SELECT p.Name, p.Notes, o.Name as ElementName
+       FROM t_operation p LEFT JOIN t_object o ON p.Object_ID = o.Object_ID
+       WHERE p.ea_guid = ? COLLATE NOCASE`)
+        .get(guid);
+    if (op) {
+        return { name: op.Name, owningElementName: op.ElementName, notes: decodeEntities(op.Notes), type: "operation" };
+    }
+    return null;
+}
+function parseFeatureLinks(db, styleEx) {
+    if (!styleEx)
+        return { sourceFeature: null, targetFeature: null };
+    let sourceFeature = null;
+    let targetFeature = null;
+    let m;
+    FEATURE_LINK_RE.lastIndex = 0;
+    while ((m = FEATURE_LINK_RE.exec(styleEx)) !== null) {
+        const side = m[1]; // S = source, E = target
+        const guid = `{${m[2]}}`;
+        const resolved = resolveFeatureGuid(db, guid);
+        const feature = resolved
+            ? { resolved: true, ...resolved }
+            : { resolved: false, present: true, guid };
+        if (side === "S")
+            sourceFeature = feature;
+        else
+            targetFeature = feature;
+    }
+    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.", {
+        elementId: z.coerce.number().describe("The Object_ID of the element to get connectors for"),
+        connectorType: z
+            .string()
+            .optional()
+            .describe("Filter by connector type (e.g., Realisation, Dependency, Association, InformationFlow, Generalization)"),
+        direction: z
+            .enum(["both", "outgoing", "incoming"])
+            .default("both")
+            .describe("Filter direction: outgoing (element is source), incoming (element is target), or both"),
+    }, READ_ONLY, async ({ elementId, connectorType, direction }) => {
+        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,
+                };
+            }
+            let conditions = [];
+            const params = [];
+            if (direction === "outgoing") {
+                conditions.push("c.Start_Object_ID = ?");
+                params.push(elementId);
+            }
+            else if (direction === "incoming") {
+                conditions.push("c.End_Object_ID = ?");
+                params.push(elementId);
+            }
+            else {
+                conditions.push("(c.Start_Object_ID = ? OR c.End_Object_ID = ?)");
+                params.push(elementId, elementId);
+            }
+            if (connectorType) {
+                conditions.push("c.Connector_Type = ?");
+                params.push(connectorType);
+            }
+            const sql = `
+          SELECT c.Connector_ID, c.Connector_Type, c.SubType, c.Name, c.Direction,
+                 c.Stereotype, c.Notes, c.SourceCard, c.DestCard,
+                 c.Start_Object_ID, c.End_Object_ID,
+                 c.SourceRole, c.DestRole, c.StyleEx,
+                 src.Name as SourceName, src.Object_Type as SourceType, src.Stereotype as SourceStereotype,
+                 dst.Name as DestName, dst.Object_Type as DestType, dst.Stereotype as DestStereotype
+          FROM t_connector c
+          LEFT JOIN t_object src ON c.Start_Object_ID = src.Object_ID
+          LEFT JOIN t_object dst ON c.End_Object_ID = dst.Object_ID
+          WHERE ${conditions.join(" AND ")}
+          ORDER BY c.Connector_Type, c.Name
+        `;
+            const rows = db.prepare(sql).all(...params);
+            const connectors = rows.map((r) => {
+                const { sourceFeature, targetFeature } = parseFeatureLinks(db, r.StyleEx);
+                return {
+                    id: r.Connector_ID,
+                    type: r.Connector_Type,
+                    subType: r.SubType,
+                    name: r.Name,
+                    direction: r.Start_Object_ID === elementId ? "outgoing" : "incoming",
+                    stereotype: r.Stereotype,
+                    notes: decodeEntities(r.Notes),
+                    sourceCard: r.SourceCard,
+                    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 },
+                    sourceFeature,
+                    targetFeature,
+                };
+            });
+            if (connectors.length === 0) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                connectors: [],
+                                totalMatched: 0,
+                                returned: 0,
+                                truncated: false,
+                                _meta: { sourceTables: ["t_connector", "t_object", "t_attribute", "t_operation"] },
+                            }, null, 2) }],
+                };
+            }
+            const response = {
+                connectors,
+                totalMatched: connectors.length,
+                returned: connectors.length,
+                truncated: false,
+                _meta: { sourceTables: ["t_connector", "t_object", "t_attribute", "t_operation"] },
+            };
+            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 connectors: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/diagrams.d.ts

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

package/dist/tools/diagrams.js

@@ -0,0 +1,225 @@
+import { READ_ONLY } from "./annotations.js";
+import { z } from "zod";
+import { decodeEntities, foldText } from "../text.js";
+import { buildPackagePath } from "../package-path.js";
+import { breakdownApplies, buildBreakdown, buildContinuation, countBy, isTruncated, limitParam, offsetParam } from "./windowing.js";
+// Reuse feature link parsing from connectors — import the module's export
+// Since the feature link logic is internal to connectors, we inline a lightweight version here
+const FEATURE_LINK_RE = /LF([SE])P=\{([^}]+)\}[^;]*/g;
+function resolveFeatureGuid(db, guid) {
+    const attr = db
+        .prepare(`SELECT a.Name, a.Notes, o.Name as ElementName
+       FROM t_attribute a LEFT JOIN t_object o ON a.Object_ID = o.Object_ID
+       WHERE a.ea_guid = ? COLLATE NOCASE`)
+        .get(guid);
+    if (attr) {
+        return { resolved: true, name: attr.Name, owningElementName: attr.ElementName, notes: decodeEntities(attr.Notes), type: "attribute" };
+    }
+    const op = db
+        .prepare(`SELECT p.Name, p.Notes, o.Name as ElementName
+       FROM t_operation p LEFT JOIN t_object o ON p.Object_ID = o.Object_ID
+       WHERE p.ea_guid = ? COLLATE NOCASE`)
+        .get(guid);
+    if (op) {
+        return { resolved: true, name: op.Name, owningElementName: op.ElementName, notes: decodeEntities(op.Notes), type: "operation" };
+    }
+    return { resolved: false, present: true, guid };
+}
+function parseFeatureLinks(db, styleEx) {
+    if (!styleEx)
+        return { sourceFeature: null, targetFeature: null };
+    let sourceFeature = null;
+    let targetFeature = null;
+    let m;
+    FEATURE_LINK_RE.lastIndex = 0;
+    while ((m = FEATURE_LINK_RE.exec(styleEx)) !== null) {
+        const side = m[1];
+        const guid = `{${m[2]}}`;
+        const feature = resolveFeatureGuid(db, guid);
+        if (side === "S")
+            sourceFeature = feature;
+        else
+            targetFeature = feature;
+    }
+    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).", {
+        diagramId: z.coerce.number().describe("The Diagram_ID to get elements for"),
+    }, READ_ONLY, async ({ diagramId }) => {
+        const db = await model.database();
+        try {
+            const diagram = db.prepare(`
+          SELECT d.Diagram_ID, d.Name, d.Diagram_Type, d.Package_ID, d.Notes,
+                 p.Name as PackageName
+          FROM t_diagram d
+          LEFT JOIN t_package p ON d.Package_ID = p.Package_ID
+          WHERE d.Diagram_ID = ?
+        `).get(diagramId);
+            if (!diagram) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: "not_found", message: `Diagram with ID ${diagramId} not found`, diagramId }, null, 2) }],
+                    isError: true,
+                };
+            }
+            const elements = db.prepare(`
+          SELECT o.Object_ID, o.Object_Type, o.Name, o.Alias, o.Stereotype, o.Note
+          FROM t_diagramobjects do_
+          JOIN t_object o ON do_.Object_ID = o.Object_ID
+          WHERE do_.Diagram_ID = ?
+          ORDER BY do_.Sequence
+        `).all(diagramId);
+            const elementResults = elements.map((e) => {
+                const result = { Object_ID: e.Object_ID, Object_Type: e.Object_Type, Name: e.Name, Alias: e.Alias, Stereotype: e.Stereotype };
+                if (e.Object_Type === "Note")
+                    result.Note = decodeEntities(e.Note);
+                return result;
+            });
+            // R2: Connectors on diagram — union of explicit links and implied connectors
+            // Explicit: rows in t_diagramlinks for this diagram
+            // Implied: connectors whose both Start_Object_ID and End_Object_ID appear in t_diagramobjects for this diagram
+            const connectorRows = db.prepare(`
+          SELECT DISTINCT c.Connector_ID, c.Connector_Type, c.SubType, c.Name, c.Direction,
+                 c.Stereotype, c.Notes, c.SourceCard, c.DestCard,
+                 c.Start_Object_ID, c.End_Object_ID,
+                 c.SourceRole, c.DestRole, c.StyleEx,
+                 src.Name as SourceName, src.Object_Type as SourceType,
+                 dst.Name as DestName, dst.Object_Type as DestType,
+                 dl.Hidden
+          FROM t_connector c
+          LEFT JOIN t_object src ON c.Start_Object_ID = src.Object_ID
+          LEFT JOIN t_object dst ON c.End_Object_ID = dst.Object_ID
+          LEFT JOIN t_diagramlinks dl ON dl.ConnectorID = c.Connector_ID AND dl.DiagramID = ?
+          WHERE
+            dl.ConnectorID IS NOT NULL
+            OR (
+              c.Start_Object_ID IN (SELECT Object_ID FROM t_diagramobjects WHERE Diagram_ID = ?)
+              AND c.End_Object_ID IN (SELECT Object_ID FROM t_diagramobjects WHERE Diagram_ID = ?)
+            )
+        `).all(diagramId, diagramId, diagramId);
+            const connectors = connectorRows.map((r) => {
+                const { sourceFeature, targetFeature } = parseFeatureLinks(db, r.StyleEx);
+                return {
+                    id: r.Connector_ID,
+                    type: r.Connector_Type,
+                    subType: r.SubType,
+                    name: r.Name,
+                    stereotype: r.Stereotype,
+                    notes: decodeEntities(r.Notes),
+                    sourceCard: r.SourceCard,
+                    destCard: r.DestCard,
+                    sourceRole: r.SourceRole || null,
+                    destRole: r.DestRole || null,
+                    hidden: r.Hidden === 1,
+                    source: { id: r.Start_Object_ID, name: r.SourceName, type: r.SourceType },
+                    dest: { id: r.End_Object_ID, name: r.DestName, type: r.DestType },
+                    sourceFeature,
+                    targetFeature,
+                };
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            diagram: {
+                                id: diagram.Diagram_ID,
+                                name: diagram.Name,
+                                type: diagram.Diagram_Type,
+                                packageId: diagram.Package_ID,
+                                packageName: diagram.PackageName,
+                                notes: decodeEntities(diagram.Notes),
+                            },
+                            elements: elementResults,
+                            connectors,
+                            _meta: {
+                                sourceTables: ["t_diagram", "t_package", "t_diagramobjects", "t_object", "t_connector", "t_diagramlinks", "t_attribute", "t_operation"],
+                                elements: { totalMatched: elementResults.length, returned: elementResults.length, truncated: false },
+                                connectors: { totalMatched: connectors.length, returned: connectors.length, truncated: false },
+                            },
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: "text", text: `Error retrieving diagram elements: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+    // R7: List and search diagrams
+    server.tool("ea_list_diagrams", "List diagrams in the model, optionally filtered by package, diagram type, and/or name substring. Each entry in `results` carries `diagramId`, `name`, `type`, `packagePath`, and `eaGuid`. Diagrams are ordered by the model's internal identity \u2014 stable but artificial, neither alphabetical nor the analyst's tree order \u2014 so adjacency carries no meaning. Walk a large result set with `offset` rather than a larger `limit`; while rows remain, `continuation` names the next call. When far more diagrams match than one window can hold, `breakdown` reports how many each type holds, so the next call can narrow by `diagramType` instead of paging.", {
+        packageId: z.coerce.number().optional().describe("Filter to diagrams in this package"),
+        diagramType: z.string().optional().describe("Filter by diagram type (e.g., Logical, Use Case, Sequence, Activity, Component)"),
+        nameContains: z.string().optional().describe("Filter to diagrams whose name contains this substring (case- and diacritic-insensitive across European Latin alphabets)"),
+        limit: limitParam(50),
+        offset: offsetParam,
+    }, READ_ONLY, async ({ packageId, diagramType, nameContains, limit, offset }) => {
+        const db = await model.database();
+        try {
+            if (packageId != null) {
+                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 sql = "SELECT Diagram_ID, Name, Diagram_Type, Package_ID, ea_guid FROM t_diagram WHERE 1=1";
+            const params = [];
+            if (packageId != null) {
+                sql += " AND Package_ID = ?";
+                params.push(packageId);
+            }
+            if (diagramType) {
+                sql += " AND Diagram_Type = ?";
+                params.push(diagramType);
+            }
+            // nameContains folds text, which SQLite cannot do, so the window is applied
+            // in JS below; the ORDER BY is what makes that window repeatable.
+            sql += " ORDER BY Diagram_ID";
+            const allRows = db.prepare(sql).all(...params);
+            let filtered = allRows;
+            if (nameContains) {
+                const folded = foldText(nameContains);
+                filtered = allRows.filter((r) => foldText(r.Name || "").includes(folded));
+            }
+            const totalMatched = filtered.length;
+            const window = filtered.slice(offset, offset + limit);
+            const truncated = isTruncated(offset, window.length, totalMatched);
+            const results = window.map((r) => ({
+                diagramId: r.Diagram_ID,
+                name: r.Name,
+                type: r.Diagram_Type,
+                packagePath: buildPackagePath(db, r.Package_ID),
+                eaGuid: r.ea_guid,
+            }));
+            const breakdown = !diagramType && breakdownApplies(totalMatched, limit)
+                ? buildBreakdown({ diagramType: countBy(filtered, (r) => r.Diagram_Type) })
+                : undefined;
+            const continuation = buildContinuation("ea_list_diagrams", { packageId, diagramType, nameContains, limit }, offset, results.length, totalMatched);
+            const response = {
+                results,
+                totalMatched,
+                returned: results.length,
+                offset,
+                truncated,
+                ...(breakdown ? { breakdown } : {}),
+                ...(continuation ? { continuation } : {}),
+                _meta: { sourceTables: ["t_diagram", "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 listing diagrams: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/elements.d.ts

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

package/dist/tools/elements.js

@@ -0,0 +1,210 @@
+import { READ_ONLY } from "./annotations.js";
+import { z } from "zod";
+import { buildPackagePath } from "../package-path.js";
+import { decodeEntities } from "../text.js";
+import { breakdownApplies, buildBreakdown, buildContinuation, isTruncated, limitParam, offsetParam } from "./windowing.js";
+const MAX_INLINE_ITEMS = 50;
+const formatMultiplicity = (a) => a.LowerBound && a.UpperBound ? `${a.LowerBound}..${a.UpperBound}` : undefined;
+export function configureElementTools(server, model) {
+    server.tool("ea_get_element", "Get full details of an Enterprise Architect element by its ID, including its `Note`, `attributes`, `operations`, the `diagrams` it appears on, and its `constraints`. Attribute multiplicity supports a requiredness inference only when the element uses multiplicities contrastively; read `_meta.attributes.multiplicityIsUniform` before making that inference — when it is true the element's attributes carry no multiplicity contrast, so a value like 1..1 is not evidence of requiredness. Attributes and operations are capped inline: `attributesTruncated`/`operationsTruncated` say whether the returned list is partial, and `attributesTotal`/`operationsTotal` give the full counts, so never infer a count from the inline list alone.", {
+        elementId: z.coerce.number().describe("The Object_ID of the element to retrieve"),
+    }, READ_ONLY, async ({ elementId }) => {
+        const db = await model.database();
+        try {
+            const element = db.prepare(`
+          SELECT o.Object_ID, o.Object_Type, o.Name, o.Alias, o.Stereotype,
+                 o.Package_ID, p.Name as PackageName, o.Note, o.Status,
+                 o.Author, o.CreatedDate, o.ModifiedDate, o.Phase, o.Complexity
+          FROM t_object o
+          LEFT JOIN t_package p ON o.Package_ID = p.Package_ID
+          WHERE o.Object_ID = ?
+        `).get(elementId);
+            if (!element) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: "not_found", message: `Element with ID ${elementId} not found`, elementId }, null, 2) }],
+                    isError: true,
+                };
+            }
+            // Get attributes
+            const allAttributes = db.prepare(`
+          SELECT ID, Name, Type, Scope, Stereotype, Notes, LowerBound, UpperBound, "Default"
+          FROM t_attribute
+          WHERE Object_ID = ?
+          ORDER BY Pos
+        `).all(elementId);
+            const attributesTruncated = allAttributes.length > MAX_INLINE_ITEMS;
+            const attributes = allAttributes.slice(0, MAX_INLINE_ITEMS).map((a) => ({
+                id: a.ID,
+                name: a.Name,
+                type: a.Type,
+                scope: a.Scope,
+                stereotype: a.Stereotype,
+                notes: a.Notes,
+                multiplicity: formatMultiplicity(a),
+                default: a.Default,
+            }));
+            // Computed over every attribute, not the inline slice, so truncation cannot flip the flag.
+            const multiplicityIsUniform = new Set(allAttributes.map(formatMultiplicity).filter((m) => m !== undefined)).size < 2;
+            // Get operations
+            const allOperations = db.prepare(`
+          SELECT OperationID, Name, Type, Scope, Stereotype, Notes
+          FROM t_operation
+          WHERE Object_ID = ?
+          ORDER BY Pos
+        `).all(elementId);
+            const operationsTruncated = allOperations.length > MAX_INLINE_ITEMS;
+            const operations = allOperations.slice(0, MAX_INLINE_ITEMS).map((op) => {
+                const params = db.prepare(`
+            SELECT Name, Type, Kind, Notes
+            FROM t_operationparams
+            WHERE OperationID = ?
+            ORDER BY Pos
+          `).all(op.OperationID);
+                return {
+                    id: op.OperationID,
+                    name: op.Name,
+                    returnType: op.Type,
+                    scope: op.Scope,
+                    stereotype: op.Stereotype,
+                    notes: op.Notes,
+                    parameters: params.map((p) => ({
+                        name: p.Name,
+                        type: p.Type,
+                        kind: p.Kind,
+                        notes: p.Notes,
+                    })),
+                };
+            });
+            // R4: Diagrams this element appears on
+            const diagramRows = db.prepare(`
+          SELECT d.Diagram_ID, d.Name, d.Diagram_Type, d.Package_ID
+          FROM t_diagramobjects do_
+          JOIN t_diagram d ON do_.Diagram_ID = d.Diagram_ID
+          WHERE do_.Object_ID = ?
+        `).all(elementId);
+            const diagrams = diagramRows.map((d) => ({
+                diagramId: d.Diagram_ID,
+                name: d.Name,
+                type: d.Diagram_Type,
+                packagePath: buildPackagePath(db, d.Package_ID),
+            }));
+            // R10: Constraints (pre-conditions, post-conditions, invariants, process rules)
+            const constraintRows = db.prepare(`
+          SELECT "Constraint" as name, ConstraintType, Notes, Status
+          FROM t_objectconstraint
+          WHERE Object_ID = ?
+          ORDER BY ConstraintType, "Constraint"
+        `).all(elementId);
+            const constraints = constraintRows.map((c) => ({
+                name: c.name,
+                type: c.ConstraintType,
+                notes: decodeEntities(c.Notes),
+                status: c.Status || null,
+            }));
+            const result = {
+                ...element,
+                Note: decodeEntities(element.Note),
+                attributes,
+                attributesTruncated,
+                attributesTotal: allAttributes.length,
+                operations,
+                operationsTruncated,
+                operationsTotal: allOperations.length,
+                diagrams,
+                constraints,
+                _meta: {
+                    sourceTables: ["t_object", "t_package", "t_attribute", "t_operation", "t_operationparams", "t_diagramobjects", "t_diagram", "t_objectconstraint"],
+                    attributes: { totalMatched: allAttributes.length, returned: attributes.length, truncated: attributesTruncated, multiplicityIsUniform },
+                    operations: { totalMatched: allOperations.length, returned: operations.length, truncated: operationsTruncated },
+                    diagrams: { totalMatched: diagramRows.length, returned: diagrams.length, truncated: false },
+                    constraints: { totalMatched: constraintRows.length, returned: constraints.length, truncated: false },
+                },
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: "text", text: `Error retrieving element: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("ea_list_elements", "List elements within a package, optionally filtered by object type. `elements` is a lightweight list (ID, type, name, alias, stereotype), grouped by element type and then ordered by the model's internal identity. That order is stable but artificial \u2014 neither alphabetical nor the analyst's tree order \u2014 so adjacency carries no meaning. Walk a large package 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 many each type holds, so the next call can narrow by `objectType` instead of paging.", {
+        packageId: z.coerce.number().describe("The Package_ID to list elements from"),
+        objectType: z
+            .string()
+            .optional()
+            .describe("Filter by object type (e.g., Class, UseCase, Activity, Screen)"),
+        limit: limitParam(50),
+        offset: offsetParam,
+    }, READ_ONLY, async ({ packageId, objectType, limit, offset }) => {
+        const db = await model.database();
+        try {
+            // Verify package exists
+            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 sql = `
+          SELECT Object_ID, Object_Type, Name, Alias, Stereotype
+          FROM t_object
+          WHERE Package_ID = ?
+        `;
+            const params = [packageId];
+            if (objectType) {
+                sql += " AND Object_Type = ?";
+                params.push(objectType);
+            }
+            // Identity, not Name: SQLite's binary collation sorts every accented initial
+            // past Z, which systematically exiles them from a truncated window.
+            sql += " ORDER BY Object_Type, Object_ID LIMIT ? OFFSET ?";
+            params.push(limit, offset);
+            const rows = db.prepare(sql).all(...params);
+            // Count total without limit for truncation reporting
+            let countSql = "SELECT COUNT(*) as cnt FROM t_object WHERE Package_ID = ?";
+            const countParams = [packageId];
+            if (objectType) {
+                countSql += " AND Object_Type = ?";
+                countParams.push(objectType);
+            }
+            const totalMatched = db.prepare(countSql).get(...countParams).cnt;
+            const truncated = isTruncated(offset, rows.length, totalMatched);
+            let breakdown;
+            if (!objectType && breakdownApplies(totalMatched, limit)) {
+                const typeRows = db
+                    .prepare("SELECT Object_Type, COUNT(*) as cnt FROM t_object WHERE Package_ID = ? GROUP BY Object_Type")
+                    .all(packageId);
+                breakdown = buildBreakdown({
+                    objectType: new Map(typeRows.filter((r) => r.Object_Type).map((r) => [String(r.Object_Type), r.cnt])),
+                });
+            }
+            const continuation = buildContinuation("ea_list_elements", { packageId, objectType, limit }, offset, rows.length, totalMatched);
+            const response = {
+                elements: rows,
+                totalMatched,
+                returned: rows.length,
+                offset,
+                truncated,
+                ...(breakdown ? { breakdown } : {}),
+                ...(continuation ? { continuation } : {}),
+                _meta: { sourceTables: ["t_object"] },
+            };
+            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 listing elements: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/packages.d.ts

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