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

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

@@ -0,0 +1,161 @@
+/********************************************************************************
+ * 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 {
+    McpDiagramScopedInputSchema,
+    AbstractMcpDiagramToolHandler,
+    McpElementsNotFoundError,
+    McpToolResult,
+    elementIds as elementIdsSchema
+} from '../../server';
+
+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}`;
+    }
+}

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

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * 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 { CommandStack, RedoAction } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { McpDiagramScopedInputSchema, McpToolError, McpToolResult, OperationMcpDiagramToolHandler } from '../../server';
+
+export const RedoInputSchema = McpDiagramScopedInputSchema.extend({
+    commandsToRedo: z.number().min(1).default(1).describe('Number of commands to redo. Defaults to 1 (most recent undone command).')
+});
+export type RedoInput = z.infer<typeof RedoInputSchema>;
+
+export const RedoOutputSchema = z.object({
+    commandsRedone: z.number().int().describe('Number of previously-undone commands re-applied.')
+});
+
+/**
+ * Redo a given number of the most recent undone actions on the command stack.
+ */
+@injectable()
+export class RedoMcpToolHandler extends OperationMcpDiagramToolHandler<RedoInput> {
+    static readonly NAME = 'redo';
+    readonly name = RedoMcpToolHandler.NAME;
+    override readonly title = 'Redo Diagram Commands';
+    readonly description =
+        'Re-apply commands that were previously undone. Defaults to redoing one command — the most recent undo — when ' +
+        '`commandsToRedo` is omitted. Use the same count you passed to `undo` to revert a complete undo cycle. ' +
+        "Throws when there's nothing on the redo stack (e.g. nothing has been undone, or the redo stack was cleared by a " +
+        'subsequent edit). Only do this on an explicit user request.';
+    readonly inputSchema = RedoInputSchema;
+    override readonly outputSchema = RedoOutputSchema;
+
+    @inject(CommandStack) protected commandStack: CommandStack;
+
+    protected async createResult({ commandsToRedo }: RedoInput): Promise<McpToolResult> {
+        if (!this.commandStack.canRedo()) {
+            throw new McpToolError(
+                'Nothing to redo (redo stack is empty; perform an undo first or accept that the redo history was cleared by a subsequent edit).'
+            );
+        }
+
+        for (let i = 0; i < commandsToRedo; i++) {
+            await this.actionDispatcher.dispatch(RedoAction.create());
+        }
+
+        return this.success('Redo successful', { commandsRedone: commandsToRedo });
+    }
+}

package/src/tools/handlers/save-model-mcp-tool-handler.ts

@@ -0,0 +1,71 @@
+/********************************************************************************
+ * 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 { ActionDispatcher, CommandStack, SaveModelAction } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { McpDiagramScopedInputSchema, AbstractMcpDiagramToolHandler, McpLogger, McpToolResult } from '../../server';
+
+export const SaveModelInputSchema = McpDiagramScopedInputSchema.extend({
+    fileUri: z.string().optional().describe('Optional destination file URI. If not provided, saves to the original source model location.')
+});
+export type SaveModelInput = z.infer<typeof SaveModelInputSchema>;
+
+export const SaveModelOutputSchema = z.object({
+    saved: z.boolean().describe('True when a save operation was dispatched; false when the model was clean and nothing was written.'),
+    fileUri: z
+        .string()
+        .optional()
+        .describe('Destination file URI when explicitly provided; absent when saving to the original source location.')
+});
+
+/** Doesn't extend `OperationMcpDiagramToolHandler` — saving a read-only model is a legitimate adopter scenario (e.g. "save as" to a writable location). */
+@injectable()
+export class SaveModelMcpToolHandler extends AbstractMcpDiagramToolHandler<SaveModelInput> {
+    static readonly NAME = 'save-model';
+    readonly name = SaveModelMcpToolHandler.NAME;
+    override readonly title = 'Save Diagram Model';
+    readonly description =
+        'Save the current diagram model to persistent storage. ' +
+        'This operation persists all changes back to the source model. ' +
+        'Only do this on an explicit user request and not as part of other tasks. ' +
+        'Optionally specify a new fileUri to save to a different location.';
+    readonly inputSchema = SaveModelInputSchema;
+    override readonly outputSchema = SaveModelOutputSchema;
+    /**
+     * Saving writes to disk — that's a mutation of the environment even though the in-memory
+     * model state isn't a target of an `Operation` dispatch. Drop the readOnly claim from the
+     * read-base default. Not destructive per the spec definition (no irreversible deletion).
+     */
+    override readonly readOnlyHint = false;
+    override readonly destructiveHint: boolean = false;
+    override readonly idempotentHint: boolean = false;
+
+    @inject(ActionDispatcher) protected actionDispatcher: ActionDispatcher;
+    @inject(CommandStack) protected commandStack: CommandStack;
+    @inject(McpLogger) protected mcpLogger: McpLogger;
+
+    protected async createResult({ fileUri }: SaveModelInput): Promise<McpToolResult> {
+        if (!this.commandStack.isDirty) {
+            this.mcpLogger.info('save-model: nothing to save');
+            return this.success('No changes to save', { saved: false, fileUri });
+        }
+
+        await this.actionDispatcher.dispatch(SaveModelAction.create({ fileUri }));
+        this.mcpLogger.info(`save-model: model saved${fileUri ? ` to ${fileUri}` : ''}`);
+        return this.success('Model saved successfully', { saved: true, fileUri });
+    }
+}

package/src/tools/handlers/session-info-mcp-tool-handler.spec.ts

@@ -0,0 +1,152 @@
+/********************************************************************************
+ * 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 { ClientSession, ClientSessionManager, CommandStack, Logger, ModelState, NullLogger } from '@eclipse-glsp/server';
+import { expect } from 'chai';
+import { Container, ContainerModule } from 'inversify';
+import { McpToolResult } from '../../server';
+import { SessionInfoMcpToolHandler } from './session-info-mcp-tool-handler';
+
+function asText(result: McpToolResult): string {
+    const block = result.content[0];
+    if (!block || block.type !== 'text') throw new Error('expected text content');
+    return block.text;
+}
+
+/** Build a {@link ClientSession} stub whose container resolves a fixed {@link ModelState} + {@link CommandStack}. */
+function makeSession(
+    id: string,
+    diagramType: string,
+    sourceUri: string | undefined,
+    isReadonly: boolean,
+    isDirty: boolean = false
+): ClientSession {
+    const sessionContainer = new Container();
+    const modelStateStub: Partial<ModelState> = { sourceUri, isReadonly };
+    sessionContainer.bind(ModelState).toConstantValue(modelStateStub as ModelState);
+    const commandStackStub: Partial<CommandStack> = { isDirty };
+    sessionContainer.bind(CommandStack).toConstantValue(commandStackStub as CommandStack);
+    return {
+        id,
+        diagramType,
+        container: sessionContainer,
+        // The handler does not exercise this dispatcher, but the interface requires it.
+        actionDispatcher: {} as ClientSession['actionDispatcher'],
+        dispose: () => {
+            //
+        }
+    };
+}
+
+class StubClientSessionManager implements ClientSessionManager {
+    constructor(private readonly sessions: ClientSession[]) {}
+
+    getOrCreateClientSession(): ClientSession {
+        throw new Error('not implemented');
+    }
+    getSession(sessionId?: string): ClientSession | undefined {
+        return this.sessions.find(s => s.id === sessionId);
+    }
+    getSessions(): ClientSession[] {
+        return this.sessions;
+    }
+    getSessionsByType(): ClientSession[] {
+        return [];
+    }
+    disposeClientSession(): boolean {
+        return true;
+    }
+    addListener(): boolean {
+        return true;
+    }
+    removeListener(): boolean {
+        return true;
+    }
+    removeListeners(): void {
+        //
+    }
+}
+
+function buildHandler(sessions: ClientSession[]): SessionInfoMcpToolHandler {
+    const container = new Container();
+    container.load(
+        new ContainerModule(bind => {
+            bind(Logger).toConstantValue(new NullLogger());
+            bind(ClientSessionManager).toConstantValue(new StubClientSessionManager(sessions));
+            bind(SessionInfoMcpToolHandler).toSelf().inSingletonScope();
+        })
+    );
+    return container.get(SessionInfoMcpToolHandler);
+}
+
+interface SessionRow {
+    sessionId: string;
+    diagramType: string;
+    sourceUri: string;
+    readOnly: boolean;
+    dirty: boolean;
+}
+
+describe('SessionInfoMcpToolHandler', () => {
+    it('summarizes each session by id and diagram type when sessions exist', () => {
+        const handler = buildHandler([
+            makeSession('session-alpha', 'workflow-diagram', 'file:///alpha.wf', false),
+            makeSession('session-beta', 'state-diagram', 'file:///beta.sd', true)
+        ]);
+
+        const result = handler['createResult']({});
+        const text = asText(result);
+        // Summary lists each session's id and diagram type — the load-bearing referenceable bits.
+        expect(text).to.include('session-alpha');
+        expect(text).to.include('session-beta');
+        expect(text).to.include('workflow-diagram');
+        expect(text).to.include('state-diagram');
+        // Full per-session detail goes via structuredContent.
+        const sessions = (result.structuredContent as { sessions: SessionRow[] }).sessions;
+        expect(sessions.map(row => row.sessionId)).to.deep.equal(['session-alpha', 'session-beta']);
+    });
+
+    it("passes through `sourceUri` and `readOnly` from each session container's ModelState via structuredContent", () => {
+        const handler = buildHandler([makeSession('s1', 'workflow-diagram', 'file:///only.wf', true, /* isDirty */ false)]);
+
+        const result = handler['createResult']({});
+        const sessions = (result.structuredContent as { sessions: SessionRow[] }).sessions;
+        expect(sessions).to.have.lengthOf(1);
+        expect(sessions[0].sourceUri).to.equal('file:///only.wf');
+        expect(sessions[0].readOnly).to.equal(true);
+        expect(sessions[0].dirty).to.equal(false);
+        // Read-only state is also surfaced in the text summary so content-only clients can see it.
+        expect(asText(result)).to.include('read-only');
+    });
+
+    it('filters to a single session when `sessionId` matches', () => {
+        const handler = buildHandler([
+            makeSession('session-alpha', 'workflow-diagram', 'file:///alpha.wf', false),
+            makeSession('session-beta', 'state-diagram', 'file:///beta.sd', true)
+        ]);
+
+        const text = asText(handler['createResult']({ sessionId: 'session-beta' }));
+
+        expect(text).to.include('session-beta');
+        expect(text).to.not.include('session-alpha');
+    });
+
+    it('throws McpToolError when the requested `sessionId` does not exist', () => {
+        const handler = buildHandler([makeSession('session-alpha', 'workflow-diagram', 'file:///alpha.wf', false)]);
+
+        expect(() => handler['createResult']({ sessionId: 'unknown' })).to.throw(/Unknown sessionId: unknown/);
+    });
+});

package/src/tools/handlers/session-info-mcp-tool-handler.ts

@@ -0,0 +1,97 @@
+/********************************************************************************
+ * 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 { ClientSessionManager, CommandStack, ModelState } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { AbstractMcpToolHandler, McpToolError, McpToolResult } from '../../server';
+
+export const SessionInfoInputSchema = z.object({
+    sessionId: z
+        .string()
+        .optional()
+        .describe('Optional filter — returns only the matching session, or throws if unknown. Omit to list all sessions.')
+});
+export type SessionInfoInput = z.infer<typeof SessionInfoInputSchema>;
+
+export const SessionInfoRowSchema = z.object({
+    sessionId: z.string(),
+    diagramType: z.string(),
+    sourceUri: z.string(),
+    readOnly: z.boolean(),
+    dirty: z.boolean().describe('True when the diagram has unsaved changes — call `save-model` to persist.')
+});
+export type SessionInfoRow = z.infer<typeof SessionInfoRowSchema>;
+
+export const SessionInfoOutputSchema = z.object({
+    sessions: z.array(SessionInfoRowSchema)
+});
+
+@injectable()
+export class SessionInfoMcpToolHandler extends AbstractMcpToolHandler<SessionInfoInput> {
+    @inject(ClientSessionManager) protected clientSessionManager: ClientSessionManager;
+
+    static readonly NAME = 'session-info';
+    readonly name = SessionInfoMcpToolHandler.NAME;
+    override readonly title = 'GLSP Session Info';
+    readonly description =
+        'Report info on the active GLSP client sessions: session id, diagram type, source uri, and read-only status. ' +
+        "Pass `sessionId` to retrieve a single session's entry; omit it to list every active session. " +
+        'Useful as a discovery tool — most other diagram-scoped tools take the `sessionId` returned here.';
+    readonly inputSchema = SessionInfoInputSchema;
+    override readonly outputSchema = SessionInfoOutputSchema;
+
+    protected createResult({ sessionId }: SessionInfoInput): McpToolResult {
+        const sessions = sessionId !== undefined ? this.singleSession(sessionId) : this.clientSessionManager.getSessions();
+        const rows = sessions.map(session => this.buildSessionRow(session));
+        return this.success(this.summarizeSessions(rows), { sessions: rows });
+    }
+
+    /** Extracts a {@link SessionInfoRow} from a {@link ClientSession}. Override to surface adopter-specific fields. */
+    protected buildSessionRow(session: ReturnType<ClientSessionManager['getSessions']>[number]): SessionInfoRow {
+        const modelState = session.container.get<ModelState>(ModelState);
+        const commandStack = session.container.get<CommandStack>(CommandStack);
+        return {
+            sessionId: session.id,
+            diagramType: session.diagramType,
+            // `ModelState.sourceUri` may be undefined for not-yet-persisted diagrams; render as empty string to keep the schema-required string shape.
+            sourceUri: modelState.sourceUri ?? '',
+            readOnly: modelState.isReadonly,
+            dirty: commandStack.isDirty
+        };
+    }
+
+    /** Builds the LLM-facing summary. Override to customize per-adopter wording. */
+    protected summarizeSessions(rows: SessionInfoRow[]): string {
+        if (rows.length === 0) {
+            return 'No active sessions.';
+        }
+        const lines = rows.map(row => {
+            const flags = [row.readOnly ? 'read-only' : undefined, row.dirty ? 'dirty' : undefined].filter(Boolean);
+            const suffix = flags.length > 0 ? `, ${flags.join(', ')}` : '';
+            return `- ${row.sessionId} (${row.diagramType}${suffix})`;
+        });
+        return `${rows.length} session(s); full details in structuredContent.\n${lines.join('\n')}`;
+    }
+
+    protected singleSession(sessionId: string): ReturnType<ClientSessionManager['getSessions']> {
+        const session = this.clientSessionManager.getSession(sessionId);
+        if (!session) {
+            throw new McpToolError(`Unknown sessionId: ${sessionId}`);
+        }
+        return [session];
+    }
+}

package/src/tools/handlers/set-selection-mcp-tool-handler.spec.ts

@@ -0,0 +1,118 @@
+/********************************************************************************
+ * 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 {
+    Action,
+    ActionDispatcher,
+    ClientId,
+    GModelElement,
+    Logger,
+    ModelState,
+    NullLogger,
+    SelectAction,
+    SelectAllAction
+} from '@eclipse-glsp/server';
+import { expect } from 'chai';
+import { Container, ContainerModule } from 'inversify';
+import { DefaultMcpLabelProvider, McpElementsNotFoundError, McpIdAliasService, McpLabelProvider, McpToolResult } from '../../server';
+import { SetSelectionInput, SetSelectionMcpToolHandler } from './set-selection-mcp-tool-handler';
+
+function makeElement(id: string, type: string): GModelElement {
+    return { id, type, children: [] } 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;
+}
+
+function makeRecordingDispatcher(): { dispatcher: ActionDispatcher; dispatched: Action[] } {
+    const dispatched: Action[] = [];
+    const dispatcher = {
+        dispatch: async (action: Action) => {
+            dispatched.push(action);
+        }
+    } as unknown as ActionDispatcher;
+    return { dispatcher, dispatched };
+}
+
+function buildHandler(elements: GModelElement[], dispatcher: ActionDispatcher): SetSelectionMcpToolHandler {
+    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(ActionDispatcher).toConstantValue(dispatcher);
+            bind(McpLabelProvider).to(DefaultMcpLabelProvider);
+            bind(SetSelectionMcpToolHandler).toSelf();
+        })
+    );
+    return container.get(SetSelectionMcpToolHandler);
+}
+
+function callCreateResult(handler: SetSelectionMcpToolHandler, params: SetSelectionInput): Promise<McpToolResult> {
+    return (handler as unknown as { createResult: (p: SetSelectionInput) => Promise<McpToolResult> }).createResult(params);
+}
+
+describe('SetSelectionMcpToolHandler', () => {
+    it('dispatches SelectAllAction(false) before SelectAction when `clear: true`', async () => {
+        const { dispatcher, dispatched } = makeRecordingDispatcher();
+        const handler = buildHandler([makeElement('n1', 'task'), makeElement('n2', 'task')], dispatcher);
+
+        await callCreateResult(handler, { sessionId: 's', selectedElementIds: ['n1'], clear: true });
+
+        expect(dispatched).to.have.lengthOf(2);
+        expect(SelectAllAction.is(dispatched[0])).to.equal(true);
+        expect((dispatched[0] as SelectAllAction).select).to.equal(false);
+        expect(SelectAction.is(dispatched[1])).to.equal(true);
+    });
+
+    it('dispatches SelectAction with resolved selected and deselected ids', async () => {
+        const { dispatcher, dispatched } = makeRecordingDispatcher();
+        const handler = buildHandler([makeElement('a', 'task'), makeElement('b', 'task'), makeElement('c', 'task')], dispatcher);
+
+        await callCreateResult(handler, { sessionId: 's', selectedElementIds: ['a', 'b'], deselectedElementIds: ['c'] });
+
+        expect(dispatched).to.have.lengthOf(1);
+        const action = dispatched[0] as SelectAction;
+        expect(action.selectedElementsIDs).to.deep.equal(['a', 'b']);
+        expect(action.deselectedElementsIDs).to.deep.equal(['c']);
+    });
+
+    it('throws McpElementsNotFoundError when an id is missing from the model', async () => {
+        const { dispatcher } = makeRecordingDispatcher();
+        const handler = buildHandler([makeElement('n1', 'task')], dispatcher);
+
+        let error: unknown;
+        try {
+            await callCreateResult(handler, { sessionId: 's', selectedElementIds: ['n1', 'ghost'] });
+        } catch (err: unknown) {
+            error = err;
+        }
+        expect(error).to.be.instanceOf(McpElementsNotFoundError);
+    });
+});