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

package/src/tools/handlers/layout-mcp-tool-handler.ts

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * 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 { LayoutEngine, LayoutOperation } from '@eclipse-glsp/server';
+import { inject, injectable, optional } from 'inversify';
+import * as z from 'zod/v4';
+import { McpDiagramScopedInputSchema, McpToolResult, OperationMcpDiagramToolHandler } from '../../server';
+
+export const LayoutInputSchema = McpDiagramScopedInputSchema;
+export type LayoutInput = z.infer<typeof LayoutInputSchema>;
+
+export const LayoutOutputSchema = z.object({
+    applied: z.boolean().describe('Always true on success — surfaced for parity with other operations.')
+});
+
+/** Not registered by default: requires an adopter-supplied `LayoutEngine` to bind, which only some GLSP servers ship. */
+@injectable()
+export class LayoutMcpToolHandler extends OperationMcpDiagramToolHandler<LayoutInput> {
+    static readonly NAME = 'layout';
+    readonly name = LayoutMcpToolHandler.NAME;
+    override readonly title = 'Auto-Layout Diagram';
+    readonly description =
+        "Trigger automatic layout computation for the given session's diagram, repositioning all nodes and " +
+        'rerouting all edges according to the configured layout engine. ' +
+        'Use this only when the user explicitly asks for "automatic layout" or similar — it overwrites every ' +
+        'manual position in the diagram and is generally a destructive change for hand-tuned layouts. ' +
+        'For targeted positional edits prefer `modify-nodes` / `modify-edges`. ' +
+        'Adopters who do not bind a `LayoutEngine` will not see this tool registered.';
+    readonly inputSchema = LayoutInputSchema;
+    override readonly outputSchema = LayoutOutputSchema;
+
+    @inject(LayoutEngine) @optional() protected layoutEngine?: LayoutEngine;
+
+    /** Skip-bind when no `LayoutEngine` is bound — every dispatch would otherwise no-op. */
+    override canRegister(): boolean {
+        return this.layoutEngine !== undefined;
+    }
+
+    protected async createResult(_params: LayoutInput): Promise<McpToolResult> {
+        await this.actionDispatcher.dispatch(LayoutOperation.create());
+        return this.success('Automatic layout applied', { applied: true });
+    }
+}

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

@@ -0,0 +1,148 @@
+/********************************************************************************
+ * 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 {
+    ElementIdentitySchema,
+    McpDiagramScopedInputSchema,
+    McpToolError,
+    McpToolResult,
+    OperationMcpDiagramToolHandler,
+    elementId as elementIdSchema,
+    position
+} from '../../server';
+import { formatNoticeList } from '../../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,140 @@
+/********************************************************************************
+ * 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 {
+    ElementIdentitySchema,
+    McpDiagramScopedInputSchema,
+    McpToolError,
+    McpToolResult,
+    OperationMcpDiagramToolHandler,
+    elementId,
+    position
+} from '../../server';
+import { formatNoticeList } from '../../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,210 @@
+/********************************************************************************
+ * 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 { DefaultMcpLabelProvider, McpElementsNotFoundError, McpIdAliasService, McpLabelProvider, McpToolResult } from '../../server';
+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']);
+        });
+    });
+});