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

package/src/resources/handlers/diagram-svg-mcp-resource-handler.ts

@@ -0,0 +1,89 @@
+/********************************************************************************
+ * 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 { ClientActionKinds, RequestExportAction } from '@eclipse-glsp/server';
+import { Role } from '@modelcontextprotocol/sdk/types.js';
+import { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import {
+    AbstractMcpDiagramResourceHandler,
+    McpDiagramScopedInputSchema,
+    McpMimeType,
+    McpProgressReporter,
+    McpResourceContent,
+    McpResourceUri,
+    McpToolError
+} from '../../server';
+
+export const DiagramSvgInputSchema = McpDiagramScopedInputSchema.extend({
+    timeoutMs: z
+        .number()
+        .int()
+        .min(100)
+        .max(60000)
+        .optional()
+        .describe('Override the default render timeout in milliseconds (100–60000). Useful for very large diagrams.')
+});
+export type DiagramSvgInput = z.infer<typeof DiagramSvgInputSchema>;
+
+/**
+ * Vector counterpart of {@link DiagramPngMcpResourceHandler}. Emits the diagram as raw SVG
+ * markup (text-encoded). No `width`/`height` knobs because SVG is vector — clients (and
+ * downstream rasterisers) scale it freely.
+ */
+@injectable()
+export class DiagramSvgMcpResourceHandler extends AbstractMcpDiagramResourceHandler<DiagramSvgInput> {
+    /** Default timeout (in ms) used when the call doesn't override `timeoutMs`. Override via subclass + rebind. */
+    protected readonly defaultTimeoutMs: number = 5000;
+
+    static readonly NAME = 'diagram-svg';
+    readonly name = DiagramSvgMcpResourceHandler.NAME;
+    override readonly title = 'Diagram Model SVG';
+    readonly description =
+        'Render the session diagram as SVG markup of its current visible state. ' +
+        'Vector format — scales without quality loss, ideal for embedding in documentation, ' +
+        'further programmatic processing, or post-export rasterisation at arbitrary resolutions. ' +
+        'Requires a connected frontend client to perform the render and is subject to a timeout if no response arrives. ' +
+        'Use `diagram-png` instead when you need a ready-to-display raster image; ' +
+        '`diagram-model` is the structured-text alternative for content-only reasoning.';
+    readonly mimeType: McpMimeType = 'image/svg+xml';
+    readonly uri: McpResourceUri = { template: 'glsp://diagrams/{sessionId}/svg' };
+    /** Both the user (visual artifact) and the assistant (visual reasoning) consume the rendered diagram. */
+    override readonly audience: Role[] = ['user', 'assistant'];
+    /** Useful when relevant, but not always-relevant — clients may skip when text-only reasoning suffices. */
+    override readonly priority = 0.6;
+    override readonly toolAlternativeInputSchema = DiagramSvgInputSchema;
+
+    @inject(McpProgressReporter) protected progress: McpProgressReporter;
+
+    @inject(ClientActionKinds) protected clientActionKinds: Set<string>;
+
+    /** Skip-bind when the GLSP client doesn't speak `RequestExportAction`. */
+    override canRegister(): boolean {
+        return this.clientActionKinds.has(RequestExportAction.KIND);
+    }
+
+    protected async createResult({ timeoutMs }: DiagramSvgInput): Promise<McpResourceContent> {
+        // Best-effort beat for clients that opted in via `_meta.progressToken`; no-ops otherwise.
+        await this.progress.emit({ progress: 0, message: 'Awaiting client-side SVG render…' });
+        const response = await this.requestAction(RequestExportAction.create('svg'), timeoutMs ?? this.defaultTimeoutMs);
+        // SVG is text-encoded — base64 encoding here would mean an exporter mis-classified its payload.
+        if (response.encoding !== 'text') {
+            throw new McpToolError(`SVG export returned unexpected encoding '${response.encoding}'; expected 'text'.`);
+        }
+        return { text: response.data };
+    }
+}

package/src/resources/index.ts

@@ -0,0 +1,20 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './handlers/diagram-png-mcp-resource-handler';
+export * from './handlers/diagram-svg-mcp-resource-handler';
+export * from './services/element-types-provider';
+export * from './services/mcp-model-serializer';

package/src/resources/services/element-types-provider.ts

@@ -0,0 +1,105 @@
+/********************************************************************************
+ * 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 { CreateEdgeOperation, CreateNodeOperation } from '@eclipse-glsp/protocol';
+import {
+    CreateEdgeOperationHandler,
+    CreateNodeOperationHandler,
+    CreateOperationHandler,
+    Logger,
+    OperationHandlerRegistry
+} from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+
+/**
+ * A discoverable creatable element type emitted by the `element-types` tool handler. Adopters
+ * may add further passthrough fields beyond these — the tool handler's structured output schema
+ * is `loose()`.
+ *
+ * @experimental
+ */
+export interface ElementTypeEntry {
+    id: string;
+    /** Human-readable display name for the element TYPE (e.g. `Manual Task`). */
+    label: string;
+    /** Adopter-supplied human-readable description; absent on the default scrape impl. */
+    description?: string;
+    /** Whether create-* / modify-* tools should pass a `text` arg for this type. Absent ⇒ unknown. */
+    acceptsText?: boolean;
+}
+
+/** Node + edge types creatable in a given diagram type. */
+export interface ElementTypes {
+    nodeTypes: ElementTypeEntry[];
+    edgeTypes: ElementTypeEntry[];
+}
+
+/**
+ * Per-diagram-type provider of creatable element types. Bound on the diagram (per-GLSP-session)
+ * container so each diagram type can supply its own list. Adopters with explicit type info
+ * typically rebind to a constant-value provider; the default scrapes
+ * {@link OperationHandlerRegistry} for backwards compatibility with adopters that haven't
+ * declared their types yet.
+ *
+ * @experimental
+ */
+export interface ElementTypesProvider {
+    get(): ElementTypes;
+}
+export const ElementTypesProvider = Symbol('ElementTypesProvider');
+
+/**
+ * Default {@link ElementTypesProvider} that scrapes the per-session {@link OperationHandlerRegistry}
+ * for {@link CreateNodeOperationHandler} / {@link CreateEdgeOperationHandler} instances and reads
+ * their `elementTypeIds`.
+ */
+@injectable()
+export class DefaultElementTypesProvider implements ElementTypesProvider {
+    @inject(OperationHandlerRegistry) protected operationHandlerRegistry: OperationHandlerRegistry;
+
+    @inject(Logger) protected logger: Logger;
+
+    /** Already-warned operation types, deduped so the warn fires once per type. */
+    protected readonly warnedTypes = new Set<string>();
+
+    get(): ElementTypes {
+        const nodeTypes: ElementTypeEntry[] = [];
+        const edgeTypes: ElementTypeEntry[] = [];
+        for (const handler of this.operationHandlerRegistry.getAll()) {
+            if (CreateNodeOperationHandler.is(handler)) {
+                handler.elementTypeIds.forEach(id => nodeTypes.push({ id, label: handler.label }));
+            } else if (CreateEdgeOperationHandler.is(handler)) {
+                handler.elementTypeIds.forEach(id => edgeTypes.push({ id, label: handler.label }));
+            } else if (CreateOperationHandler.is(handler)) {
+                this.warnUnrecognizedOperationType(handler);
+            }
+        }
+        return { nodeTypes, edgeTypes };
+    }
+
+    /** Once-per-type warn when a `CreateOperationHandler` carries an unrecognized `operationType`. */
+    protected warnUnrecognizedOperationType(handler: CreateOperationHandler): void {
+        const operationType = handler.operationType;
+        if (this.warnedTypes.has(operationType)) {
+            return;
+        }
+        this.warnedTypes.add(operationType);
+        this.logger.warn(
+            `DefaultElementTypesProvider: ignoring CreateOperationHandler with operationType '${operationType}' — ` +
+                `expected '${CreateNodeOperation.KIND}' or '${CreateEdgeOperation.KIND}'. Rebind ElementTypesProvider for custom operation types.`
+        );
+    }
+}

package/src/resources/services/mcp-model-serializer.ts

@@ -0,0 +1,211 @@
+/********************************************************************************
+ * 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/graph';
+import { Dimension, GModelSerializer, Logger, Point } from '@eclipse-glsp/server';
+import { inject, injectable, postConstruct } from 'inversify';
+import { McpStructuredContent } from '../../server/mcp-handler-shared';
+import { McpIdAliasService } from '../../server/mcp-id-alias-service';
+import { objectArrayToMarkdownTable } from '../../util';
+
+export const McpModelSerializer = Symbol('McpModelSerializer');
+
+/** Loose JSON-object shape mirroring `GModelSerializer.createSchema` output — open-keyed because
+ * GModel attributes vary per element type. Reads must narrow before use. */
+export interface SerializedElement {
+    [key: string]: unknown;
+}
+
+/**
+ * Transforms a graphical model into a representation suitable for LLM consumption. Markdown and
+ * JSON are both reasonable formats; the default impl ({@link MarkdownMcpModelSerializer}) emits
+ * Markdown for {@link serialize}/{@link serializeArray} and an object payload for
+ * {@link serializeStructured} (the dual-emit `structuredContent` counterpart). Aliasing of element
+ * ids happens internally via the per-session {@link McpIdAliasService}.
+ *
+ * @experimental
+ */
+export interface McpModelSerializer {
+    /** Serializes a single element (and its descendants). */
+    serialize(element: GModelElement): string;
+
+    /** Serializes an array of elements; duplicates introduced by hierarchy are removed. */
+    serializeArray(elements: GModelElement[]): string;
+
+    /**
+     * Structured-content counterpart of {@link serialize} for dual-emit
+     * (`CallToolResult.structuredContent`). The shape is intentionally open: `{ elements: [...] }`
+     * with each entry carrying `id` + `type` + adopter-specific attrs (passthrough).
+     */
+    serializeStructured(element: GModelElement): McpStructuredContent;
+
+    /** Structured-content counterpart of {@link serializeArray}. */
+    serializeStructuredArray(elements: GModelElement[]): McpStructuredContent;
+}
+
+/**
+ * Default {@link McpModelSerializer} — emits Markdown with one H1 section per element type
+ * followed by a table of all elements of that type. Flattens the GModel tree, drops keys with
+ * no LLM value (`cssClasses`, `revision`, `layout`, etc., see {@link keysToRemove}), truncates
+ * position+size to integers and derives a `bounds` rectangle so the LLM doesn't redo arithmetic.
+ *
+ * Generic: no control over element order or per-type attribute order, since no specific GLSP
+ * adopter is known. Adopters override (see workflow's `WorkflowMcpModelSerializer`) when
+ * semantic ordering matters.
+ */
+@injectable()
+export class MarkdownMcpModelSerializer implements McpModelSerializer {
+    @inject(GModelSerializer) protected gModelSerializer: GModelSerializer;
+    @inject(McpIdAliasService) protected aliasService: McpIdAliasService;
+    @inject(Logger) protected logger: Logger;
+
+    protected keysToRemove: string[] = [
+        'cssClasses',
+        'revision',
+        'layout',
+        'args',
+        'layoutOptions',
+        'alignment',
+        'children',
+        'routingPoints',
+        'resizeLocations',
+        'parent'
+    ];
+
+    /** Warn once per binding when the bare default is used — subclasses suppress via the constructor check. */
+    @postConstruct()
+    protected warnIfGenericDefault(): void {
+        if (this.constructor === MarkdownMcpModelSerializer) {
+            this.logger.warn(
+                'Using generic MarkdownMcpModelSerializer; bind a diagram-specific subclass via ' +
+                    'DefaultMcpDiagramModule.bindModelSerializer() for richer LLM output.'
+            );
+        }
+    }
+
+    serialize(element: GModelElement): string {
+        return this.serializeArray([element]);
+    }
+
+    serializeArray(elements: GModelElement[]): string {
+        return Object.entries(this.buildAliasedTypeBuckets(elements))
+            .filter(([, bucket]) => bucket.length > 0)
+            .flatMap(([type, bucket]) => [`# ${type}`, objectArrayToMarkdownTable(bucket)])
+            .join('\n');
+    }
+
+    serializeStructured(element: GModelElement): McpStructuredContent {
+        return this.serializeStructuredArray([element]);
+    }
+
+    serializeStructuredArray(elements: GModelElement[]): McpStructuredContent {
+        return {
+            elements: Object.values(this.buildAliasedTypeBuckets(elements))
+                .filter(bucket => bucket.length > 0)
+                .flat()
+        };
+    }
+
+    /** Common pipeline: prepare, dedupe by id, group by type, alias ids — used by both renders. */
+    protected buildAliasedTypeBuckets(elements: GModelElement[]): Record<string, SerializedElement[]> {
+        const elementsByTypeArray = elements.map(element => this.prepareElement(element));
+        const result: Record<string, SerializedElement[]> = {};
+        const allKeys = new Set(elementsByTypeArray.flatMap(obj => Object.keys(obj)));
+        allKeys.forEach(key => {
+            const combined = elementsByTypeArray.flatMap(obj => obj[key] ?? []);
+            result[key] = Array.from(new Map(combined.map(item => [item.id, item])).values()).map(item => this.applyAlias(item));
+        });
+        return result;
+    }
+
+    protected applyAlias(element: SerializedElement): SerializedElement {
+        for (const field of ['id', 'sourceId', 'targetId', 'parentId'] as const) {
+            const value = element[field];
+            if (typeof value === 'string') {
+                element[field] = this.aliasService.alias(value);
+            }
+        }
+        return element;
+    }
+
+    protected prepareElement(element: GModelElement): Record<string, SerializedElement[]> {
+        const schema = this.gModelSerializer.createSchema(element) as unknown as SerializedElement;
+        const elements = this.flattenStructure(schema, element.parent?.id);
+
+        const result: Record<string, SerializedElement[]> = {};
+        elements.forEach(elem => {
+            this.removeKeys(elem);
+            this.combinePositionAndSize(elem);
+            const type = typeof elem.type === 'string' ? elem.type : 'unknown';
+            (result[type] ??= []).push(elem);
+        });
+
+        return result;
+    }
+
+    protected flattenStructure(element: SerializedElement, parentId?: string): SerializedElement[] {
+        const newElement: SerializedElement = { ...element };
+        const result: SerializedElement[] = [newElement];
+        const children = newElement.children;
+        if (Array.isArray(children)) {
+            const ownId = typeof newElement.id === 'string' ? newElement.id : undefined;
+            children.forEach(child =>
+                this.flattenStructure(child as SerializedElement, ownId).forEach(descendant => result.push(descendant))
+            );
+        }
+        newElement.parentId = parentId;
+        return result;
+    }
+
+    protected removeKeys(element: SerializedElement): void {
+        for (const key of Object.keys(element)) {
+            if (this.keysToRemove.includes(key)) {
+                delete element[key];
+            }
+        }
+    }
+
+    protected combinePositionAndSize(element: SerializedElement): void {
+        const position = element.position;
+        if (!Point.is(position)) {
+            return;
+        }
+        const x = Math.trunc(position.x);
+        const y = Math.trunc(position.y);
+        element.position = { x, y };
+
+        // Omit `size` and `bounds` when an element has no explicit geometry yet (e.g., a freshly
+        // created node whose `.size()` has not been applied). Emitting `{width: 0, height: 0}`
+        // would mislead an LLM consumer into "fixing" placeholder bounds. Visual rendering on
+        // the GLSP/sprotty client is unaffected — those nodes are laid out via CSS regardless.
+        const size = element.size;
+        if (!Dimension.is(size) || (Math.trunc(size.width) === 0 && Math.trunc(size.height) === 0)) {
+            delete element.size;
+            delete element.bounds;
+            return;
+        }
+
+        const width = Math.trunc(size.width);
+        const height = Math.trunc(size.height);
+        element.size = { width, height };
+        element.bounds = {
+            left: x,
+            right: x + width,
+            top: y,
+            bottom: y + height
+        };
+    }
+}

package/src/server/glsp-mcp-server.spec.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 { NullLogger } from '@eclipse-glsp/server';
+import { McpServer, RegisteredResource } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import * as z from 'zod/v4';
+import { DefaultGLSPMcpServer } from './glsp-mcp-server';
+
+describe('DefaultGLSPMcpServer', () => {
+    function makeServer(): { wrapper: DefaultGLSPMcpServer; sdk: McpServer } {
+        const sdk = new McpServer({ name: 'test', version: '1.0.0' }, { capabilities: {} });
+        const wrapper = new DefaultGLSPMcpServer(sdk, { dataMode: 'tools' }, new NullLogger());
+        return { wrapper, sdk };
+    }
+
+    it('tracks every registerTool call so listTools returns the registered set', () => {
+        const { wrapper } = makeServer();
+        wrapper.registerTool('alpha', { description: 'first', inputSchema: { x: z.string() } }, async () => ({ content: [] }));
+        wrapper.registerTool('beta', { description: 'second' }, async () => ({ content: [] }));
+
+        const names = wrapper.listTools().map(tool => tool.description);
+        expect(names).to.have.members(['first', 'second']);
+        expect(wrapper.listTools()).to.have.lengthOf(2);
+    });
+
+    it('tracks registerResource (static URI) and listResources reflects it by name', () => {
+        const { wrapper } = makeServer();
+        wrapper.registerResource('my-resource', 'glsp://test', { title: 'res', mimeType: 'text/plain' }, async () => ({
+            contents: [{ uri: 'glsp://test', text: 'ok' }]
+        }));
+
+        const resources = wrapper.listResources();
+        expect(resources).to.have.lengthOf(1);
+        expect((resources[0] as RegisteredResource).name).to.equal('my-resource');
+        expect((resources[0] as RegisteredResource).title).to.equal('res');
+    });
+
+    it('tracks registerPrompt and listPrompts reflects it by description', () => {
+        const { wrapper } = makeServer();
+        wrapper.registerPrompt('describe', { description: 'desc' }, async () => ({ messages: [] }));
+
+        const prompts = wrapper.listPrompts();
+        expect(prompts).to.have.lengthOf(1);
+        expect(prompts[0].description).to.equal('desc');
+    });
+
+    it('getRawServer() returns the exact SDK instance passed in (escape hatch identity)', () => {
+        const { wrapper, sdk } = makeServer();
+        expect(wrapper.getRawServer()).to.equal(sdk);
+    });
+
+    it('dispose() invokes close() on the underlying SDK server', () => {
+        const { wrapper, sdk } = makeServer();
+        const closeSpy = sinon.spy(sdk, 'close');
+        wrapper.dispose();
+        expect(closeSpy.calledOnce).to.be.true;
+    });
+});