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

package/src/server/mcp-diagram-module.ts

@@ -0,0 +1,248 @@
+/********************************************************************************
+ * 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 { applyBindingTarget, BindingTarget, ClientSessionInitializer, GLSPModule, InstanceMultiBinding } from '@eclipse-glsp/server';
+import { interfaces } from 'inversify';
+import { DiagramPngMcpResourceHandler, DiagramSvgMcpResourceHandler } from '../resources';
+import { DefaultElementTypesProvider, ElementTypesProvider } from '../resources/services/element-types-provider';
+import { MarkdownMcpModelSerializer, McpModelSerializer } from '../resources/services/mcp-model-serializer';
+import {
+    CountElementsMcpToolHandler,
+    CreateEdgesMcpToolHandler,
+    CreateNodesMcpToolHandler,
+    DeleteElementsMcpToolHandler,
+    DiagramModelMcpToolHandler,
+    GetSelectionMcpToolHandler,
+    LayoutMcpToolHandler,
+    ModifyEdgesMcpToolHandler,
+    ModifyNodesMcpToolHandler,
+    QueryElementsMcpToolHandler,
+    RedoMcpToolHandler,
+    SaveModelMcpToolHandler,
+    SetSelectionMcpToolHandler,
+    SetViewMcpToolHandler,
+    UndoMcpToolHandler,
+    ValidateDiagramMcpToolHandler
+} from '../tools';
+import {
+    McpDiagramPromptHandlerFactory,
+    McpDiagramPromptHandlerRegistry,
+    McpDiagramPromptHandlerRegistryInitializer
+} from './mcp-diagram-prompt-handler-registry';
+import {
+    McpDiagramResourceHandlerFactory,
+    McpDiagramResourceHandlerRegistry,
+    McpDiagramResourceHandlerRegistryInitializer
+} from './mcp-diagram-resource-handler-registry';
+import {
+    McpDiagramToolHandlerFactory,
+    McpDiagramToolHandlerRegistry,
+    McpDiagramToolHandlerRegistryInitializer
+} from './mcp-diagram-tool-handler-registry';
+import { DefaultMcpIdAliasService, McpIdAliasService } from './mcp-id-alias-service';
+import { McpDiagramScopedInput } from './mcp-input-schemas';
+import { DefaultMcpLabelProvider, McpLabelProvider } from './mcp-label-provider';
+import { AbstractMcpDiagramPromptHandler, McpDiagramPromptHandlerConstructor } from './mcp-prompt-handler';
+import { AbstractMcpDiagramResourceHandler, McpDiagramResourceHandlerConstructor } from './mcp-resource-handler';
+import { BaseMcpDiagramToolHandler, McpDiagramToolHandlerConstructor } from './mcp-tool-handler';
+
+/**
+ * Per-GLSP-client-session DI module for the MCP server. Loaded inside `configureDiagramModule`
+ * so each `ClientSession.container` gets its own instance of session-scoped services.
+ *
+ * Binds the {@link McpIdAliasService}, the {@link McpModelSerializer}, the
+ * {@link ElementTypesProvider}, and the diagram-scope handler-constructor multi-bindings
+ * (`McpDiagram*HandlerConstructor`). Adopters subclass and override the `bind*` hooks to swap
+ * single-instance services and the `configure*` hooks to extend the multi-binding handler sets.
+ *
+ * @example
+ * ```ts
+ * class WorkflowMcpDiagramModule extends DefaultMcpDiagramModule {
+ *     // Single-instance binding: return the class.
+ *     protected override bindModelSerializer(): BindingTarget<McpModelSerializer> {
+ *         return WorkflowMcpModelSerializer;
+ *     }
+ *     // Multi-binding: extend or rebind the default set.
+ *     protected override configureToolHandlers(binding) {
+ *         super.configureToolHandlers(binding);
+ *         binding.add(WorkflowExtraTool);
+ *         binding.rebind(CreateNodesMcpToolHandler, WorkflowCreateNodesMcpToolHandler);
+ *     }
+ * }
+ * new WorkflowServerModule().configureDiagramModule(
+ *     new WorkflowDiagramModule(...),
+ *     elkLayoutModule,
+ *     new WorkflowMcpDiagramModule()
+ * );
+ * ```
+ */
+export abstract class AbstractMcpDiagramModule extends GLSPModule {
+    protected bind!: interfaces.Bind;
+    protected rebind!: interfaces.Rebind;
+
+    protected override configure(
+        bind: interfaces.Bind,
+        _unbind: interfaces.Unbind,
+        isBound: interfaces.IsBound,
+        rebind: interfaces.Rebind
+    ): void {
+        this.bind = bind;
+        this.rebind = rebind;
+        const context = { bind, isBound };
+        applyBindingTarget(context, McpIdAliasService, this.bindIdAliasService()).inSingletonScope();
+        applyBindingTarget(context, McpLabelProvider, this.bindLabelProvider()).inSingletonScope();
+        applyBindingTarget(context, McpModelSerializer, this.bindModelSerializer()).inSingletonScope();
+        applyBindingTarget(context, ElementTypesProvider, this.bindElementTypesProvider()).inSingletonScope();
+        this.configureMultiBinding(new InstanceMultiBinding<McpDiagramToolHandlerConstructor>(McpDiagramToolHandlerConstructor), binding =>
+            this.configureToolHandlers(binding as InstanceMultiBinding<McpDiagramToolHandlerConstructor>)
+        );
+        this.configureMultiBinding(
+            new InstanceMultiBinding<McpDiagramResourceHandlerConstructor>(McpDiagramResourceHandlerConstructor),
+            binding => this.configureResourceHandlers(binding as InstanceMultiBinding<McpDiagramResourceHandlerConstructor>)
+        );
+        this.configureMultiBinding(
+            new InstanceMultiBinding<McpDiagramPromptHandlerConstructor>(McpDiagramPromptHandlerConstructor),
+            binding => this.configurePromptHandlers(binding as InstanceMultiBinding<McpDiagramPromptHandlerConstructor>)
+        );
+        this.configureHandlerRegistries();
+    }
+
+    /**
+     * Bind the per-GLSP-session handler registries, factories, and {@link ClientSessionInitializer}s
+     * that populate the registries at session-open. Adopters typically don't override.
+     *
+     * Each kind (tool / resource / prompt) follows the same shape:
+     *  - `Registry` — singleton-per-session, holds instantiated handlers keyed by `name`.
+     *  - `Factory` — `dynamicValue` that calls `ctx.container.resolve(constructor)`, so the
+     *    handler's `@inject(...)` fields resolve against the live `ClientSession.container`.
+     *  - `RegistryInitializer` — at session-open, reads the constructor multi-binding (added by
+     *    adopter `configure*Handlers` overrides) and instantiates each via the factory.
+     *    Picked up by Inversify alongside core's own `ClientSessionInitializer`s
+     *    (`OperationHandlerRegistryInitializer` etc.).
+     */
+    protected configureHandlerRegistries(): void {
+        this.bind(McpDiagramToolHandlerRegistry).toSelf().inSingletonScope();
+        this.bind<McpDiagramToolHandlerFactory>(McpDiagramToolHandlerFactory).toDynamicValue(
+            ctx => (constructor: McpDiagramToolHandlerConstructor) =>
+                ctx.container.resolve<BaseMcpDiagramToolHandler<McpDiagramScopedInput>>(constructor)
+        );
+        this.bind(McpDiagramToolHandlerRegistryInitializer).toSelf().inSingletonScope();
+        this.bind(ClientSessionInitializer).toService(McpDiagramToolHandlerRegistryInitializer);
+
+        this.bind(McpDiagramResourceHandlerRegistry).toSelf().inSingletonScope();
+        this.bind<McpDiagramResourceHandlerFactory>(McpDiagramResourceHandlerFactory).toDynamicValue(
+            ctx => (constructor: McpDiagramResourceHandlerConstructor) =>
+                ctx.container.resolve<AbstractMcpDiagramResourceHandler<McpDiagramScopedInput>>(constructor)
+        );
+        this.bind(McpDiagramResourceHandlerRegistryInitializer).toSelf().inSingletonScope();
+        this.bind(ClientSessionInitializer).toService(McpDiagramResourceHandlerRegistryInitializer);
+
+        this.bind(McpDiagramPromptHandlerRegistry).toSelf().inSingletonScope();
+        this.bind<McpDiagramPromptHandlerFactory>(McpDiagramPromptHandlerFactory).toDynamicValue(
+            ctx => (constructor: McpDiagramPromptHandlerConstructor) =>
+                ctx.container.resolve<AbstractMcpDiagramPromptHandler<McpDiagramScopedInput>>(constructor)
+        );
+        this.bind(McpDiagramPromptHandlerRegistryInitializer).toSelf().inSingletonScope();
+        this.bind(ClientSessionInitializer).toService(McpDiagramPromptHandlerRegistryInitializer);
+    }
+
+    /**
+     * {@link McpIdAliasService} binding. Override to swap in a custom alias strategy. Bind the
+     * shipped `NullMcpIdAliasService` (passthrough) to expose raw GLSP ids on the wire — useful
+     * for diagnostic readability or when token cost isn't a concern.
+     */
+    protected bindIdAliasService(): BindingTarget<McpIdAliasService> {
+        return DefaultMcpIdAliasService;
+    }
+
+    /**
+     * {@link McpLabelProvider} binding. Override to teach MCP about adopter-specific label
+     * locations (e.g., labels nested in header components or compartments). One override here
+     * covers every read-side echo and every write-side label-edit operation.
+     */
+    protected bindLabelProvider(): BindingTarget<McpLabelProvider> {
+        return DefaultMcpLabelProvider;
+    }
+
+    /**
+     * {@link McpModelSerializer} binding. Override to swap in a diagram-type-specific serializer
+     * (e.g. one that emits JSON, or knows the adopter's element schema). Per-session scope means
+     * each diagram type provides its own serializer without a server-level rebind.
+     */
+    protected bindModelSerializer(): BindingTarget<McpModelSerializer> {
+        return MarkdownMcpModelSerializer;
+    }
+
+    /**
+     * {@link ElementTypesProvider} binding. Override to ship a constant-value list of creatable
+     * element types for the adopter's diagram type instead of the default impl that scrapes
+     * {@link OperationHandlerRegistry} (noisy for non-trivial diagrams).
+     */
+    protected bindElementTypesProvider(): BindingTarget<ElementTypesProvider> {
+        return DefaultElementTypesProvider;
+    }
+
+    /**
+     * Override to add or replace diagram-scope tool handlers. Adopters typically
+     * `super.configureToolHandlers(binding)` to keep the defaults, then `binding.add(MyTool)`
+     * for additions or `binding.rebind(StandardTool, MyTool)` for overrides.
+     */
+    protected configureToolHandlers(binding: InstanceMultiBinding<McpDiagramToolHandlerConstructor>): void {
+        binding.add(CreateNodesMcpToolHandler);
+        binding.add(CreateEdgesMcpToolHandler);
+        binding.add(DeleteElementsMcpToolHandler);
+        binding.add(SaveModelMcpToolHandler);
+        binding.add(ValidateDiagramMcpToolHandler);
+        binding.add(DiagramModelMcpToolHandler);
+        binding.add(QueryElementsMcpToolHandler);
+        binding.add(CountElementsMcpToolHandler);
+        binding.add(ModifyNodesMcpToolHandler);
+        binding.add(ModifyEdgesMcpToolHandler);
+        binding.add(UndoMcpToolHandler);
+        binding.add(RedoMcpToolHandler);
+        binding.add(GetSelectionMcpToolHandler);
+        binding.add(SetSelectionMcpToolHandler);
+        binding.add(SetViewMcpToolHandler);
+        // Auto-skips at session-open via `canRegister()` when no `LayoutEngine` is bound.
+        binding.add(LayoutMcpToolHandler);
+    }
+
+    /** See {@link configureToolHandlers}. */
+    protected configureResourceHandlers(binding: InstanceMultiBinding<McpDiagramResourceHandlerConstructor>): void {
+        binding.add(DiagramPngMcpResourceHandler);
+        binding.add(DiagramSvgMcpResourceHandler);
+    }
+
+    /**
+     * See {@link configureToolHandlers}. No diagram-scope prompts ship by default — the shipped
+     * `describe-diagram` and `suggest-improvements` prompts are diagram-type-agnostic and bound
+     * server-scope. Adopters add their own diagram-type-specific prompts here.
+     */
+    protected configurePromptHandlers(_binding: InstanceMultiBinding<McpDiagramPromptHandlerConstructor>): void {
+        // empty by default
+    }
+}
+
+/**
+ * Default {@link AbstractMcpDiagramModule} entry point. Adopters who don't need overrides
+ * use it directly: `new DefaultMcpDiagramModule()`. Adopters with customizations subclass
+ * `AbstractMcpDiagramModule` (or this class) and override the `bind*` / `configure*` hooks.
+ *
+ * @experimental The MCP integration is under active development. Option names, schema shapes,
+ * and handler contracts MAY change in minor releases until the feature graduates from
+ * experimental status.
+ */
+export class DefaultMcpDiagramModule extends AbstractMcpDiagramModule {}

package/src/server/mcp-diagram-prompt-handler-registry.ts

@@ -0,0 +1,59 @@
+/********************************************************************************
+ * 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 { Args, ClientSessionInitializer, Registry } from '@eclipse-glsp/server';
+import { inject, injectable, optional } from 'inversify';
+import { McpDiagramScopedInput } from './mcp-input-schemas';
+import { AbstractMcpDiagramPromptHandler, McpDiagramPromptHandlerConstructor } from './mcp-prompt-handler';
+
+/** See {@link McpDiagramToolHandlerFactory} — same lifecycle pattern, applied to prompt handlers. */
+export type McpDiagramPromptHandlerFactory = (
+    constructor: McpDiagramPromptHandlerConstructor
+) => AbstractMcpDiagramPromptHandler<McpDiagramScopedInput>;
+export const McpDiagramPromptHandlerFactory = Symbol('McpDiagramPromptHandlerFactory');
+
+/** See {@link McpDiagramToolHandlerRegistry} — same lifecycle pattern, applied to prompt handlers. */
+@injectable()
+export class McpDiagramPromptHandlerRegistry extends Registry<string, AbstractMcpDiagramPromptHandler<McpDiagramScopedInput>> {
+    registerHandler(handler: AbstractMcpDiagramPromptHandler<McpDiagramScopedInput>): boolean {
+        return this.register(handler.name, handler);
+    }
+}
+
+/** See {@link McpDiagramToolHandlerRegistryInitializer} — same lifecycle pattern, applied to prompt handlers. */
+@injectable()
+export class McpDiagramPromptHandlerRegistryInitializer implements ClientSessionInitializer {
+    @inject(McpDiagramPromptHandlerFactory) protected factory: McpDiagramPromptHandlerFactory;
+
+    @inject(McpDiagramPromptHandlerConstructor)
+    @optional()
+    protected constructors: McpDiagramPromptHandlerConstructor[] = [];
+
+    @inject(McpDiagramPromptHandlerRegistry) protected registry: McpDiagramPromptHandlerRegistry;
+
+    initialize(_args?: Args): void {
+        for (const constructor of this.constructors) {
+            try {
+                this.registry.registerHandler(this.factory(constructor));
+            } catch (err: unknown) {
+                throw new Error(
+                    `Failed to instantiate MCP diagram prompt handler '${constructor.name}': ${(err as Error).message}. ` +
+                        'Check your DiagramModule bindings.'
+                );
+            }
+        }
+    }
+}

package/src/server/mcp-diagram-resource-handler-registry.ts

@@ -0,0 +1,73 @@
+/********************************************************************************
+ * 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 { Args, ClientId, ClientSessionInitializer, Logger, Registry, TEMPORARY_CLIENT_ID } from '@eclipse-glsp/server';
+import { inject, injectable, optional } from 'inversify';
+import { McpDiagramScopedInput } from './mcp-input-schemas';
+import { AbstractMcpDiagramResourceHandler, McpDiagramResourceHandlerConstructor } from './mcp-resource-handler';
+
+/** See {@link McpDiagramToolHandlerFactory} — same lifecycle pattern, applied to resource handlers. */
+export type McpDiagramResourceHandlerFactory = (
+    constructor: McpDiagramResourceHandlerConstructor
+) => AbstractMcpDiagramResourceHandler<McpDiagramScopedInput>;
+export const McpDiagramResourceHandlerFactory = Symbol('McpDiagramResourceHandlerFactory');
+
+/** See {@link McpDiagramToolHandlerRegistry} — same lifecycle pattern, applied to resource handlers. */
+@injectable()
+export class McpDiagramResourceHandlerRegistry extends Registry<string, AbstractMcpDiagramResourceHandler<McpDiagramScopedInput>> {
+    registerHandler(handler: AbstractMcpDiagramResourceHandler<McpDiagramScopedInput>): boolean {
+        return this.register(handler.name, handler);
+    }
+}
+
+/** See {@link McpDiagramToolHandlerRegistryInitializer} — same lifecycle pattern, applied to resource handlers. */
+@injectable()
+export class McpDiagramResourceHandlerRegistryInitializer implements ClientSessionInitializer {
+    @inject(McpDiagramResourceHandlerFactory) protected factory: McpDiagramResourceHandlerFactory;
+
+    @inject(McpDiagramResourceHandlerConstructor)
+    @optional()
+    protected constructors: McpDiagramResourceHandlerConstructor[] = [];
+
+    @inject(McpDiagramResourceHandlerRegistry) protected registry: McpDiagramResourceHandlerRegistry;
+
+    @inject(ClientId) protected clientId: string;
+
+    @inject(Logger) protected logger: Logger;
+
+    initialize(_args?: Args): void {
+        // See {@link McpDiagramToolHandlerRegistryInitializer.initialize} for the probe rationale.
+        const isProbe = this.clientId === TEMPORARY_CLIENT_ID;
+        for (const constructor of this.constructors) {
+            let handler: AbstractMcpDiagramResourceHandler<McpDiagramScopedInput>;
+            try {
+                handler = this.factory(constructor);
+            } catch (err: unknown) {
+                throw new Error(
+                    `Failed to instantiate MCP diagram resource handler '${constructor.name}': ${(err as Error).message}. ` +
+                        'Check your DiagramModule bindings.'
+                );
+            }
+            if (!handler.canRegister()) {
+                if (!isProbe) {
+                    this.logger.warn(`Skipping MCP diagram resource handler '${handler.name}': canRegister() returned false.`);
+                }
+                continue;
+            }
+            this.registry.registerHandler(handler);
+        }
+    }
+}

package/src/server/mcp-diagram-tool-handler-registry.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 { Args, ClientId, ClientSessionInitializer, Logger, Registry, TEMPORARY_CLIENT_ID } from '@eclipse-glsp/server';
+import { inject, injectable, optional } from 'inversify';
+import { McpDiagramScopedInput } from './mcp-input-schemas';
+import { BaseMcpDiagramToolHandler, McpDiagramToolHandlerConstructor } from './mcp-tool-handler';
+
+/**
+ * Per-GLSP-session factory that resolves a {@link McpDiagramToolHandlerConstructor} against the
+ * per-session Inversify container. Calls `container.resolve(ctor)` so `@inject(...)` fields on
+ * the handler are filled from the live `ClientSession.container` (alias service, model state,
+ * action dispatcher, etc.).
+ *
+ * Mirrors core's {@link OperationHandlerFactory} pattern in `DiagramModule`.
+ */
+export type McpDiagramToolHandlerFactory = (
+    constructor: McpDiagramToolHandlerConstructor
+) => BaseMcpDiagramToolHandler<McpDiagramScopedInput>;
+export const McpDiagramToolHandlerFactory = Symbol('McpDiagramToolHandlerFactory');
+
+/**
+ * Per-GLSP-session registry holding one {@link BaseMcpDiagramToolHandler} instance per
+ * `metadata.name`. Populated at GLSP-session-open by {@link McpDiagramToolHandlerRegistryInitializer},
+ * read at MCP-tool-call time by the launcher's dispatcher (looks up the right session, gets its
+ * registry, resolves the handler by name, invokes `createResult`).
+ *
+ * Bound singleton-per-session on the diagram container.
+ */
+@injectable()
+export class McpDiagramToolHandlerRegistry extends Registry<string, BaseMcpDiagramToolHandler<McpDiagramScopedInput>> {
+    /** Convenience that derives the key from `handler.name` so callers don't repeat themselves. */
+    registerHandler(handler: BaseMcpDiagramToolHandler<McpDiagramScopedInput>): boolean {
+        return this.register(handler.name, handler);
+    }
+}
+
+/**
+ * {@link ClientSessionInitializer} that runs at GLSP-session-open. Reads the per-session
+ * constructor multi-binding ({@link McpDiagramToolHandlerConstructor}) and instantiates each
+ * handler via the {@link McpDiagramToolHandlerFactory}, registering the instance with the
+ * per-session {@link McpDiagramToolHandlerRegistry}.
+ *
+ * Same shape as core's `OperationHandlerRegistryInitializer`.
+ */
+@injectable()
+export class McpDiagramToolHandlerRegistryInitializer implements ClientSessionInitializer {
+    @inject(McpDiagramToolHandlerFactory) protected factory: McpDiagramToolHandlerFactory;
+
+    @inject(McpDiagramToolHandlerConstructor)
+    @optional()
+    protected constructors: McpDiagramToolHandlerConstructor[] = [];
+
+    @inject(McpDiagramToolHandlerRegistry) protected registry: McpDiagramToolHandlerRegistry;
+
+    @inject(ClientId) protected clientId: string;
+
+    @inject(Logger) protected logger: Logger;
+
+    initialize(_args?: Args): void {
+        // Suppress the canRegister-false warn during core's `DefaultGlobalActionProvider`
+        // startup probe — that probe runs on a throwaway container with empty action-kind set,
+        // so `canRegister()` returning false there is structural, not a real opt-out.
+        const isProbe = this.clientId === TEMPORARY_CLIENT_ID;
+        for (const constructor of this.constructors) {
+            let handler: BaseMcpDiagramToolHandler<McpDiagramScopedInput>;
+            try {
+                handler = this.factory(constructor);
+            } catch (err: unknown) {
+                throw new Error(
+                    `Failed to instantiate MCP diagram tool handler '${constructor.name}': ${(err as Error).message}. ` +
+                        'Check your DiagramModule bindings.'
+                );
+            }
+            if (!handler.canRegister()) {
+                if (!isProbe) {
+                    this.logger.warn(`Skipping MCP diagram tool handler '${handler.name}': canRegister() returned false.`);
+                }
+                continue;
+            }
+            this.registry.registerHandler(handler);
+        }
+    }
+}

package/src/server/mcp-handler-shared.spec.ts

@@ -0,0 +1,53 @@
+/********************************************************************************
+ * 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 } from '@eclipse-glsp/server';
+import { expect } from 'chai';
+import { McpToolError, resolveActiveSessionId } from './mcp-handler-shared';
+
+function stubSessionManager(sessionIds: string[]): ClientSessionManager {
+    return { getSessions: () => sessionIds.map(id => ({ id })) } as unknown as ClientSessionManager;
+}
+
+describe('resolveActiveSessionId', () => {
+    it('returns the explicit session id when it matches an open session', () => {
+        const result = resolveActiveSessionId(stubSessionManager(['alpha', 'beta']), 'alpha');
+        expect(result).to.equal('alpha');
+    });
+
+    it('defaults to the only open session when sessionId is omitted', () => {
+        const result = resolveActiveSessionId(stubSessionManager(['solo']), undefined);
+        expect(result).to.equal('solo');
+    });
+
+    it('throws McpToolError listing the open sessions when ambiguous', () => {
+        expect(() => resolveActiveSessionId(stubSessionManager(['session-a', 'session-b']), undefined)).to.throw(
+            McpToolError,
+            /Multiple sessions open.*session-a.*session-b/
+        );
+    });
+
+    it('throws McpToolError when no sessions are open', () => {
+        expect(() => resolveActiveSessionId(stubSessionManager([]), undefined)).to.throw(McpToolError, /No open diagram sessions/);
+    });
+
+    it('throws McpToolError when an explicit sessionId does not match any open session', () => {
+        expect(() => resolveActiveSessionId(stubSessionManager(['real-session']), 'ghost')).to.throw(
+            McpToolError,
+            /Unknown sessionId: ghost/
+        );
+    });
+});