@eclipse-glsp/server-mcp 2.7.0-next.10

package/src/tools/handlers/modify-edges-mcp-tool-handler.ts

@@ -0,0 +1,142 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import { ChangeRoutingPointsOperation, GEdge, ReconnectEdgeOperation } from '@eclipse-glsp/server';
+import { injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { McpToolError, McpToolResult } from '../../server/mcp-handler-shared';
+import { ElementIdentitySchema, McpDiagramScopedInputSchema, elementId as elementIdSchema, position } from '../../server/mcp-input-schemas';
+import { OperationMcpDiagramToolHandler } from '../../server/mcp-tool-handler';
+import { formatNoticeList } from '../../util/mcp-util';
+
+/** Single edge-modification entry. Strict so an LLM-typoed field surfaces as a validation error instead of being silently dropped. */
+export const ModifyEdgeSpecSchema = z.strictObject({
+    elementId: elementIdSchema,
+    sourceElementId: z.string().optional().describe('ID of the source element (must exist in the diagram)'),
+    targetElementId: z.string().optional().describe('ID of the target element (must exist in the diagram)'),
+    routingPoints: z
+        .array(position)
+        .optional()
+        .describe(
+            'Optional array of routing point coordinates that allow for a complex edge path. ' +
+                'Using an empty array removes all routing points.'
+        )
+});
+
+export const ModifyEdgesInputSchema = McpDiagramScopedInputSchema.extend({
+    edges: z
+        .array(ModifyEdgeSpecSchema)
+        .min(1)
+        .describe('Array of edge changes — each entry needs `elementId` plus the fields to update. Must include at least one change.')
+});
+export type ModifyEdgesInput = z.infer<typeof ModifyEdgesInputSchema>;
+
+export const ModifyEdgesOutputSchema = z.object({
+    modifiedEdges: z.array(ElementIdentitySchema).describe('Identity of each edge whose change request was dispatched.'),
+    dispatchedCommands: z.number().int().describe('Number of underlying GLSP operations dispatched.'),
+    errors: z.array(z.string()).describe('Per-input failure messages; absent or empty when every input succeeded.')
+});
+
+@injectable()
+export class ModifyEdgesMcpToolHandler extends OperationMcpDiagramToolHandler<ModifyEdgesInput> {
+    static readonly NAME = 'modify-edges';
+    readonly name = ModifyEdgesMcpToolHandler.NAME;
+    override readonly title = 'Modify Diagram Edges';
+    readonly description =
+        'Modify one or more existing edges by reconnecting their source/target endpoints or rewriting their routing points. ' +
+        'Reconnection (provide both `sourceElementId` and `targetElementId`) and routing-point edits are mutually exclusive ' +
+        'per change entry — a reconnect recomputes the path from scratch and ignores `routingPoints`. ' +
+        'Pass an empty `routingPoints` array to remove all routing points (snap to a straight line). ' +
+        'This operation modifies the diagram state and requires user approval. ' +
+        'For nodes (position/size/text), use `modify-nodes` instead.';
+    readonly inputSchema = ModifyEdgesInputSchema;
+    override readonly outputSchema = ModifyEdgesOutputSchema;
+
+    protected async createResult({ edges }: ModifyEdgesInput): Promise<McpToolResult> {
+        const elements = this.lookupElements(edges, change => change.elementId);
+
+        // Type-validate so non-edge ids surface a clear error instead of "model element not found"
+        // from the dispatched operation handler. Aliases are sequential across all element kinds,
+        // so an LLM passing an arbitrary id may hit a node here.
+        const wrongType = elements
+            .filter(([, element]) => !(element instanceof GEdge))
+            .map(([change, element]) => `'${change.elementId}' (type '${element.type}')`);
+        if (wrongType.length) {
+            throw new McpToolError(`modify-edges accepts edges only — got: ${wrongType.join(', ')}. Use modify-nodes for nodes.`);
+        }
+
+        // Dispatch in parallel via `allSettled` so one failed edge surfaces in `errors`
+        // instead of rejecting the whole call and losing the other outcomes.
+        const dispatched: Array<{ promise: Promise<void>; realId: string; inputId: string }> = [];
+        const errors: string[] = [];
+        const modifiedRealIds = new Set<string>();
+        elements.forEach(([change]) => {
+            const { routingPoints } = change;
+            const realId = this.aliasService.lookup(change.elementId);
+            const sourceElementId = change.sourceElementId ? this.aliasService.lookup(change.sourceElementId) : undefined;
+            const targetElementId = change.targetElementId ? this.aliasService.lookup(change.targetElementId) : undefined;
+
+            if ((sourceElementId && !targetElementId) || (!sourceElementId && targetElementId)) {
+                errors.push(`Both source and target ID are required for input: ${JSON.stringify(change)}`);
+                return;
+            }
+
+            if (sourceElementId && targetElementId) {
+                const source = this.modelState.index.find(sourceElementId);
+                if (!source) {
+                    errors.push(`Source element not found: ${sourceElementId}`);
+                    return;
+                }
+                const target = this.modelState.index.find(targetElementId);
+                if (!target) {
+                    errors.push(`Target element not found: ${targetElementId}`);
+                    return;
+                }
+
+                const operation = ReconnectEdgeOperation.create({ edgeElementId: realId, sourceElementId, targetElementId });
+                dispatched.push({ promise: this.actionDispatcher.dispatch(operation), realId, inputId: change.elementId });
+                modifiedRealIds.add(realId);
+                // Routing-point changes are skipped during a reconnect — the edge's path is recomputed from scratch.
+                return;
+            }
+
+            if (routingPoints) {
+                const operation = ChangeRoutingPointsOperation.create([{ elementId: realId, newRoutingPoints: routingPoints }]);
+                dispatched.push({ promise: this.actionDispatcher.dispatch(operation), realId, inputId: change.elementId });
+                modifiedRealIds.add(realId);
+            }
+        });
+
+        const results = await Promise.allSettled(dispatched.map(entry => entry.promise));
+        results.forEach((result, i) => {
+            if (result.status === 'rejected') {
+                const { realId, inputId } = dispatched[i];
+                const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+                errors.push(`Failed to modify edge '${inputId}': ${reason}`);
+                // The dispatch failed, so this id was *not* modified — drop it from the success list.
+                modifiedRealIds.delete(realId);
+            }
+        });
+
+        const modifiedEdges = [...modifiedRealIds]
+            .map(realId => this.describeElement(realId))
+            .filter((entry): entry is NonNullable<typeof entry> => entry !== undefined);
+        return this.success(
+            `Successfully modified ${edges.length - errors.length} edge(s) (in ${dispatched.length} commands)${formatNoticeList('errors', errors)}`,
+            { modifiedEdges, dispatchedCommands: dispatched.length, errors }
+        );
+    }
+}

package/src/tools/handlers/modify-nodes-mcp-tool-handler.ts

@@ -0,0 +1,134 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import { ApplyLabelEditOperation, ChangeBoundsOperation, GEdge, GShapeElement } from '@eclipse-glsp/server';
+import { injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { McpToolError, McpToolResult } from '../../server/mcp-handler-shared';
+import { ElementIdentitySchema, McpDiagramScopedInputSchema, elementId, position } from '../../server/mcp-input-schemas';
+import { OperationMcpDiagramToolHandler } from '../../server/mcp-tool-handler';
+import { formatNoticeList } from '../../util/mcp-util';
+
+/** Strict — any unknown field on the size object surfaces as a validation error. */
+export const NodeSizeSchema = z.strictObject({
+    width: z.number().positive().describe('Width of the element in diagram space (must be > 0).'),
+    height: z.number().positive().describe('Height of the element in diagram space (must be > 0).')
+});
+
+/** Single node-modification entry. Strict so an LLM-typoed field surfaces as a validation error instead of being silently dropped. */
+export const ModifyNodeSpecSchema = z.strictObject({
+    elementId,
+    position: position.optional().describe('Position where the node should be moved to (absolute diagram coordinates)'),
+    size: NodeSizeSchema.optional().describe('New size of the node'),
+    text: z.string().optional().describe("Label text to use instead (given that the element's type allows for labels).")
+});
+
+export const ModifyNodesInputSchema = McpDiagramScopedInputSchema.extend({
+    nodes: z
+        .array(ModifyNodeSpecSchema)
+        .min(1)
+        .describe('Array of node changes — each entry needs `elementId` plus the fields to update. Must include at least one change.')
+});
+export type ModifyNodesInput = z.infer<typeof ModifyNodesInputSchema>;
+
+export const ModifyNodesOutputSchema = z.object({
+    modifiedNodes: z
+        .array(ElementIdentitySchema)
+        .describe('Identity of each node whose change request was dispatched (post-modification labels).'),
+    dispatchedCommands: z.number().int().describe('Number of underlying GLSP operations dispatched (a single change may yield several).'),
+    warnings: z
+        .array(z.string())
+        .describe(
+            'Soft notices for inputs whose change applied with caveats (e.g. `text` supplied for a node whose type has no editable label).'
+        )
+});
+
+@injectable()
+export class ModifyNodesMcpToolHandler extends OperationMcpDiagramToolHandler<ModifyNodesInput> {
+    static readonly NAME = 'modify-nodes';
+    readonly name = ModifyNodesMcpToolHandler.NAME;
+    override readonly title = 'Modify Diagram Nodes';
+    readonly description =
+        'Modify one or more existing nodes by changing their position, size, and/or label text. ' +
+        'When modifying position or size, absolutely consider the visual alignment with other nodes — ' +
+        'use `query-elements` (inspect mode) first to understand the layout. ' +
+        'Each change entry can include any combination of `position`, `size`, and `text`; omitted fields keep their current value. ' +
+        'This operation modifies the diagram state and requires user approval. ' +
+        'For edges (reconnect / routing-points), use `modify-edges` instead.';
+    readonly inputSchema = ModifyNodesInputSchema;
+    override readonly outputSchema = ModifyNodesOutputSchema;
+
+    protected async createResult({ nodes }: ModifyNodesInput): Promise<McpToolResult> {
+        const elements = this.lookupElements(nodes, change => change.elementId);
+
+        // Reject edge ids — they have no `position`/`size` semantics and would fail downstream
+        // with a misleading "model element not found" error from the operation handler. Aliases
+        // are sequential across all element kinds, so an LLM passing an arbitrary id may hit an edge.
+        const wrongType = elements.filter(([, element]) => element instanceof GEdge).map(([change]) => `'${change.elementId}'`);
+        if (wrongType.length) {
+            throw new McpToolError(`modify-nodes does not accept edges — got: ${wrongType.join(', ')}. Use modify-edges for edges.`);
+        }
+
+        // Reject any other non-shape kinds (labels, compartments, ports, custom kinds) — they
+        // reach the index too and would silently produce no-op or undefined-bounds operations.
+        const nonShape = elements.filter(([, element]) => !(element instanceof GShapeElement)).map(([change]) => `'${change.elementId}'`);
+        if (nonShape.length) {
+            throw new McpToolError(
+                `modify-nodes only accepts shape elements — got: ${nonShape.join(', ')}. ` +
+                    'Use `query-elements` (inspect mode) to find shape ids, or pick the parent shape.'
+            );
+        }
+
+        // Modifications are independent of each other — dispatch in parallel.
+        const promises: Promise<void>[] = [];
+        const warnings: string[] = [];
+        elements.forEach(([change, element]) => {
+            // Guaranteed non-null and shape-typed by the missing-elements / nonShape checks above.
+            const resolved = element as GShapeElement;
+            const { size, position, text } = change;
+            const realId = this.aliasService.lookup(change.elementId);
+
+            if (size || position) {
+                const newSize = size ?? resolved.size;
+                const newPosition = position ?? resolved.position;
+
+                const operation = ChangeBoundsOperation.create([{ elementId: realId, newSize, newPosition }]);
+                promises.push(this.actionDispatcher.dispatch(operation));
+            }
+
+            if (text) {
+                const labelId = this.labelProvider.getLabel(resolved)?.id;
+                if (labelId) {
+                    promises.push(this.actionDispatcher.dispatch(ApplyLabelEditOperation.create({ labelId, text })));
+                } else {
+                    warnings.push(
+                        `Ignored \`text\` for '${change.elementId}' (type '${resolved.type}') — this element has no editable label.`
+                    );
+                }
+            }
+        });
+
+        await Promise.all(promises);
+
+        const modifiedNodes = nodes
+            .map(change => this.describeElement(change.elementId))
+            .filter((entry): entry is NonNullable<typeof entry> => entry !== undefined);
+        return this.success(
+            `Successfully modified ${nodes.length} node(s) (in ${promises.length} commands)` + formatNoticeList('warnings', warnings),
+            { modifiedNodes, dispatchedCommands: promises.length, warnings }
+        );
+    }
+}

package/src/tools/handlers/query-elements-mcp-tool-handler.spec.ts

@@ -0,0 +1,212 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import { ClientId, GLabel, GModelElement, Logger, ModelState, NullLogger } from '@eclipse-glsp/server';
+import { expect } from 'chai';
+import { Container, ContainerModule } from 'inversify';
+import { McpModelSerializer } from '../../resources/services/mcp-model-serializer';
+import { McpElementsNotFoundError, McpToolResult } from '../../server/mcp-handler-shared';
+import { McpIdAliasService } from '../../server/mcp-id-alias-service';
+import { DefaultMcpLabelProvider, McpLabelProvider } from '../../server/mcp-label-provider';
+import { QueryElementsInput, QueryElementsMcpToolHandler } from './query-elements-mcp-tool-handler';
+
+function makeLabel(text: string): GLabel {
+    // Set the prototype so `child instanceof GLabel` checks in the handler return true.
+    return Object.assign(Object.create(GLabel.prototype), { id: 'label', type: 'label', text, children: [] }) as GLabel;
+}
+
+function makeElement(id: string, type: string, labelText?: string): GModelElement {
+    return {
+        id,
+        type,
+        children: labelText !== undefined ? [makeLabel(labelText)] : []
+    } as unknown as GModelElement;
+}
+
+function makeModelState(elements: GModelElement[]): ModelState {
+    const byId = new Map(elements.map(el => [el.id, el]));
+    return {
+        index: {
+            allIds: () => [...byId.keys()],
+            get: (id: string) => byId.get(id),
+            find: (id: string) => byId.get(id)
+        }
+    } as unknown as ModelState;
+}
+
+interface CapturingSerializer extends McpModelSerializer {
+    /** Element arrays the handler passed to {@link serializeStructuredArray}, in call order. */
+    capturedArrays: GModelElement[][];
+}
+
+function makeCapturingSerializer(): CapturingSerializer {
+    const capturedArrays: GModelElement[][] = [];
+    return {
+        capturedArrays,
+        serialize: () => 'serialized',
+        serializeStructured: () => ({}),
+        serializeArray: elements => elements.map(el => `- ${el.id} (${el.type})`).join('\n'),
+        serializeStructuredArray: elements => {
+            capturedArrays.push(elements);
+            return { elements: elements.map(el => ({ id: el.id, type: el.type })) };
+        }
+    };
+}
+
+function buildHandler(elements: GModelElement[], serializer: McpModelSerializer = makeCapturingSerializer()): QueryElementsMcpToolHandler {
+    const container = new Container();
+    container.load(
+        new ContainerModule(bind => {
+            bind(Logger).toConstantValue(new NullLogger());
+            bind(ClientId).toConstantValue('test-session');
+            bind(ModelState).toConstantValue(makeModelState(elements));
+            bind(McpIdAliasService).toConstantValue({
+                lookup: (id: string) => id,
+                alias: (id: string) => id
+            } as McpIdAliasService);
+            bind(McpModelSerializer).toConstantValue(serializer);
+            bind(McpLabelProvider).to(DefaultMcpLabelProvider);
+            bind(QueryElementsMcpToolHandler).toSelf();
+        })
+    );
+    return container.get(QueryElementsMcpToolHandler);
+}
+
+interface ListStructured {
+    mode: 'list';
+    matches: { id: string; type: string; label?: string }[];
+    truncated: boolean;
+}
+interface InspectStructured {
+    mode: 'inspect';
+    elements: { id: string; type: string }[];
+}
+
+function callCreateResult(handler: QueryElementsMcpToolHandler, params: QueryElementsInput): Promise<McpToolResult> {
+    return (handler as unknown as { createResult: (p: QueryElementsInput) => Promise<McpToolResult> }).createResult(params);
+}
+
+describe('QueryElementsMcpToolHandler', () => {
+    describe('list mode (no `elementIds`)', () => {
+        it('filters by `types` (only matching types are returned)', async () => {
+            const handler = buildHandler([
+                makeElement('n1', 'task:manual', 'Build'),
+                makeElement('n2', 'task:automated', 'Deploy'),
+                makeElement('e1', 'edge')
+            ]);
+
+            const result = await callCreateResult(handler, { sessionId: 's', types: ['task:manual'] });
+            const structured = result.structuredContent as unknown as ListStructured;
+            expect(structured.mode).to.equal('list');
+            expect(structured.matches).to.have.lengthOf(1);
+            expect(structured.matches[0].id).to.equal('n1');
+        });
+
+        it('matches `labelMatch` case-insensitively against direct GLabel children', async () => {
+            const handler = buildHandler([
+                makeElement('n1', 'task', 'Build artifact'),
+                makeElement('n2', 'task', 'Deploy artifact'),
+                makeElement('n3', 'task', 'Validate spec')
+            ]);
+
+            const result = await callCreateResult(handler, { sessionId: 's', labelMatch: 'ARTIFACT' });
+            const ids = (result.structuredContent as unknown as ListStructured).matches.map(m => m.id);
+            expect(ids).to.have.members(['n1', 'n2']);
+        });
+
+        it('combines `types` and `labelMatch` as AND', async () => {
+            const handler = buildHandler([
+                makeElement('n1', 'task:manual', 'Build artifact'),
+                makeElement('n2', 'task:automated', 'Build artifact')
+            ]);
+
+            const result = await callCreateResult(handler, {
+                sessionId: 's',
+                types: ['task:manual'],
+                labelMatch: 'build'
+            });
+            const matches = (result.structuredContent as unknown as ListStructured).matches;
+            expect(matches).to.have.lengthOf(1);
+            expect(matches[0].id).to.equal('n1');
+        });
+
+        it('caps results at `limit` and reports `truncated: true`', async () => {
+            const elements = Array.from({ length: 10 }, (_, i) => makeElement(`n${i}`, 'task'));
+            const handler = buildHandler(elements);
+
+            const result = await callCreateResult(handler, { sessionId: 's', limit: 3 });
+            const structured = result.structuredContent as unknown as ListStructured;
+            expect(structured.matches).to.have.lengthOf(3);
+            expect(structured.truncated).to.equal(true);
+        });
+
+        it('surfaces a no-match message and empty matches when nothing matches', async () => {
+            const handler = buildHandler([makeElement('n1', 'task', 'foo')]);
+
+            const result = await callCreateResult(handler, { sessionId: 's', types: ['nonexistent'] });
+            const text = (result.content[0] as { text: string }).text;
+            expect(text).to.include('No elements matched');
+            expect((result.structuredContent as unknown as ListStructured).matches).to.deep.equal([]);
+        });
+    });
+
+    describe('inspect mode (with `elementIds`)', () => {
+        it('resolves the requested ids and forwards the matching elements to the serializer', async () => {
+            const elements = [makeElement('n1', 'task:manual', 'Build'), makeElement('n2', 'task:automated', 'Deploy')];
+            const serializer = makeCapturingSerializer();
+            const handler = buildHandler(elements, serializer);
+
+            const result = await callCreateResult(handler, { sessionId: 's', elementIds: ['n1', 'n2'] });
+
+            // The handler delegated rendering to the injected serializer with the exact
+            // GModelElement instances looked up from the model index — not just the ids. Inspect
+            // mode also probes per-element to detect container expansion before rendering, so the
+            // final array call is what produces the structuredContent — assert on that one.
+            expect(serializer.capturedArrays.length).to.be.greaterThan(0);
+            const finalCall = serializer.capturedArrays[serializer.capturedArrays.length - 1];
+            expect(finalCall).to.deep.equal(elements);
+
+            const structured = result.structuredContent as unknown as InspectStructured;
+            expect(structured.mode).to.equal('inspect');
+        });
+
+        it('throws McpElementsNotFoundError when an id is missing from the model', async () => {
+            const handler = buildHandler([makeElement('n1', 'task')]);
+
+            try {
+                await callCreateResult(handler, { sessionId: 's', elementIds: ['n1', 'unknown'] });
+                expect.fail('expected McpElementsNotFoundError');
+            } catch (err) {
+                expect(err).to.be.instanceOf(McpElementsNotFoundError);
+            }
+        });
+
+        it('ignores `types` / `labelMatch` / `limit` when `elementIds` is set', async () => {
+            const handler = buildHandler([makeElement('n1', 'task:manual'), makeElement('n2', 'task:automated')]);
+
+            const result = await callCreateResult(handler, {
+                sessionId: 's',
+                elementIds: ['n1'],
+                types: ['task:automated'], // would exclude n1 in list mode
+                labelMatch: 'nope',
+                limit: 0 // intentionally would fail validation in list mode
+            });
+            const structured = result.structuredContent as unknown as InspectStructured;
+            expect(structured.mode).to.equal('inspect');
+            expect(structured.elements.map(e => e.id)).to.deep.equal(['n1']);
+        });
+    });
+});

package/src/tools/handlers/query-elements-mcp-tool-handler.ts

@@ -0,0 +1,157 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import { GModelElement } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { McpModelSerializer } from '../../resources/services/mcp-model-serializer';
+import { McpElementsNotFoundError, McpToolResult } from '../../server/mcp-handler-shared';
+import { McpDiagramScopedInputSchema, elementIds as elementIdsSchema } from '../../server/mcp-input-schemas';
+import { AbstractMcpDiagramToolHandler } from '../../server/mcp-tool-handler';
+
+export const QueryElementsInputSchema = McpDiagramScopedInputSchema.extend({
+    elementIds: elementIdsSchema
+        .optional()
+        .describe('Inspect-mode trigger. When set, returns rich per-element data and ignores the filter fields. Throws on unknown id.'),
+    types: z.array(z.string()).optional().describe('List-mode type filter. Empty/omitted = any. Ignored when `elementIds` is set.'),
+    labelMatch: z.string().optional().describe('List-mode case-insensitive substring on direct-child `GLabel.text`.'),
+    limit: z.number().int().min(1).max(1000).optional().describe('List-mode cap, 1–1000. Defaults to 100.')
+});
+export type QueryElementsInput = z.infer<typeof QueryElementsInputSchema>;
+
+export const QueryElementMatchSchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    label: z.string().optional()
+});
+
+/** `.loose()` lets adopter element types attach extra fields (position, size, …) without widening the schema each time. */
+export const DiagramElementSchema = z
+    .object({
+        id: z.string(),
+        type: z.string(),
+        parentId: z.string().optional()
+    })
+    .loose();
+
+export const QueryElementsOutputSchema = z.object({
+    mode: z.enum(['list', 'inspect']).describe('Echoes which mode the call ran in.'),
+    matches: z.array(QueryElementMatchSchema).optional().describe('Present in `list` mode: slim id/type/label entries.'),
+    elements: z.array(DiagramElementSchema).optional().describe('Present in `inspect` mode: rich per-element detail.'),
+    truncated: z.boolean().optional().describe('Present in `list` mode: true when more elements matched than `limit`.'),
+    expandedFromContainers: z
+        .array(z.string())
+        .optional()
+        .describe(
+            'Present in `inspect` mode when one or more requested ids referred to containers — lists those container ids. ' +
+                'The `elements` array then includes the container plus its descendants.'
+        )
+});
+
+/** Two-mode element query — list/filter or inspect-by-id, discriminated by `elementIds` presence. */
+@injectable()
+export class QueryElementsMcpToolHandler extends AbstractMcpDiagramToolHandler<QueryElementsInput> {
+    static readonly NAME = 'query-elements';
+    readonly name = QueryElementsMcpToolHandler.NAME;
+    override readonly title = 'Query Diagram Elements';
+    readonly description =
+        'Find or inspect elements in the session diagram. Pass `elementIds` to inspect specific ' +
+        'elements in detail (rich per-element data). Pass `types` and/or `labelMatch` to search by ' +
+        'filter (slim id/type/label summaries with truncation). Useful as a precursor to the ' +
+        'create/modify/delete tools, and a cheaper alternative to `diagram-model` on large diagrams.';
+    readonly inputSchema = QueryElementsInputSchema;
+    override readonly outputSchema = QueryElementsOutputSchema;
+
+    @inject(McpModelSerializer) protected serializer: McpModelSerializer;
+
+    /** List-mode result cap when the call doesn't override `limit`. Override via subclass. */
+    protected readonly defaultLimit: number = 100;
+
+    protected async createResult(params: QueryElementsInput): Promise<McpToolResult> {
+        return params.elementIds && params.elementIds.length > 0 ? this.inspect(params.elementIds) : this.list(params);
+    }
+
+    protected inspect(inputIds: string[]): McpToolResult {
+        const { realIds, missingIds } = this.resolveIds(inputIds);
+        if (missingIds.length > 0) {
+            throw new McpElementsNotFoundError(missingIds);
+        }
+        const elements: GModelElement[] = realIds.map(id => this.modelState.index.get(id)!);
+        // Per-input serialize lets us identify which inputs caused expansion: the serializer
+        // walks descendants for containers, so a 1-input call may produce N output entries.
+        // The structural-children check the previous version used overstated this — a leaf node
+        // with a label child counts as having `children.length > 0` but doesn't produce extra
+        // entries because the serializer's adjuster drops labels.
+        const expandedFromContainers = elements
+            .filter(element => {
+                // `serializeStructuredArray` returns an open `Record<string, unknown>` per the
+                // `McpStructuredContent` contract; narrow before reading `.elements.length`.
+                const entries = this.serializer.serializeStructuredArray([element]).elements;
+                return Array.isArray(entries) && entries.length > 1;
+            })
+            .map(element => this.aliasService.alias(element.id));
+        // Serializer's `serializeStructuredArray` already returns `{ elements: [...] }`; spread to keep one source of truth.
+        return this.success(this.summarizeInspect(elements, expandedFromContainers), {
+            mode: 'inspect',
+            ...this.serializer.serializeStructuredArray(elements),
+            ...(expandedFromContainers.length > 0 ? { expandedFromContainers } : {})
+        });
+    }
+
+    /** Builds the LLM-facing summary for inspect mode. Override to customize per-adopter wording. */
+    protected summarizeInspect(elements: GModelElement[], expandedFromContainers: string[]): string {
+        const lines = elements.map(element => `- ${this.aliasService.alias(element.id)} (${element.type})`);
+        const expansionNote =
+            expandedFromContainers.length > 0 ? `\nContainer(s) ${expandedFromContainers.join(', ')} expanded to include descendants.` : '';
+        return `Inspected ${elements.length} element(s); full data in structuredContent.\n${lines.join('\n')}${expansionNote}`;
+    }
+
+    protected list({ types, labelMatch, limit }: QueryElementsInput): McpToolResult {
+        const cap = limit ?? this.defaultLimit;
+        const typeFilter = types && types.length > 0 ? new Set(types) : undefined;
+        const needle = labelMatch?.toLowerCase();
+
+        const matches: { id: string; type: string; label?: string }[] = [];
+        let truncated = false;
+        for (const id of this.modelState.index.allIds()) {
+            const element = this.modelState.index.get(id);
+            if (!element) {
+                continue;
+            }
+            if (typeFilter && !typeFilter.has(element.type)) {
+                continue;
+            }
+            const label = this.labelProvider.getLabel(element)?.text;
+            if (needle !== undefined && !label?.toLowerCase().includes(needle)) {
+                continue;
+            }
+            if (matches.length >= cap) {
+                truncated = true;
+                break;
+            }
+            matches.push({ id: this.aliasService.alias(element.id), type: element.type, ...(label !== undefined ? { label } : {}) });
+        }
+
+        const summary = matches.length === 0 ? 'No elements matched the query.' : this.renderMarkdown(matches, truncated);
+        return this.success(summary, { mode: 'list', matches, truncated });
+    }
+
+    protected renderMarkdown(matches: { id: string; type: string; label?: string }[], truncated: boolean): string {
+        const rows = matches.map(match => `- ${match.id} (${match.type})${match.label ? ` — "${match.label}"` : ''}`).join('\n');
+        const tail = truncated ? '\n\n_(truncated — increase `limit` or refine filters to see more)_' : '';
+        return `Matched ${matches.length} element${matches.length === 1 ? '' : 's'}:\n${rows}${tail}`;
+    }
+}