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

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

@@ -0,0 +1,90 @@
+/********************************************************************************
+ * 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, SelectAction, SelectAllAction } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { AbstractMcpDiagramToolHandler, McpDiagramScopedInputSchema, McpToolResult, elementIds } from '../../server';
+
+export const SetSelectionInputSchema = McpDiagramScopedInputSchema.extend({
+    selectedElementIds: elementIds
+        .optional()
+        .describe('Element IDs to select. Pass an empty array (or omit + set `clear: true`) to clear the selection.'),
+    deselectedElementIds: elementIds.optional().describe('Element IDs to remove from the selection. Used to subtract without replacing.'),
+    clear: z
+        .boolean()
+        .optional()
+        .describe('When true, clear the existing selection before applying `selectedElementIds`. Defaults to false (additive).')
+});
+export type SetSelectionInput = z.infer<typeof SetSelectionInputSchema>;
+
+export const SetSelectionOutputSchema = z.object({
+    selectedElementIds: z.array(z.string()).describe('Aliased ids requested for selection.'),
+    deselectedElementIds: z.array(z.string()).describe('Aliased ids requested for deselection.'),
+    cleared: z.boolean().describe('Whether the existing selection was cleared before applying.')
+});
+
+/**
+ * Pushes a selection change to the client. Counterpart to `get-selection` — useful for the
+ * agent to direct a human reviewer's attention to elements it just modified ("here's what I
+ * touched"), or to chain follow-up tools that rely on the visible selection.
+ *
+ * Read-write hint is honest: the viewport selection state is part of the client environment
+ * even though the underlying GModel is unaffected.
+ */
+@injectable()
+export class SetSelectionMcpToolHandler extends AbstractMcpDiagramToolHandler<SetSelectionInput> {
+    static readonly NAME = 'set-selection';
+    readonly name = SetSelectionMcpToolHandler.NAME;
+    override readonly title = 'Set Diagram Selection';
+    readonly description =
+        'Set the selection of elements on the client UI. Useful to direct a reviewer to a ' +
+        'set of elements (e.g. those just created or modified). Pass `clear: true` to replace ' +
+        'the existing selection rather than add to it.';
+    readonly inputSchema = SetSelectionInputSchema;
+    override readonly outputSchema = SetSelectionOutputSchema;
+    override readonly readOnlyHint = false;
+
+    @inject(ActionDispatcher) protected actionDispatcher: ActionDispatcher;
+
+    protected async createResult({ selectedElementIds, deselectedElementIds, clear }: SetSelectionInput): Promise<McpToolResult> {
+        const resolvedSelected = this.resolveExistingIds(selectedElementIds);
+        const resolvedDeselected = this.resolveExistingIds(deselectedElementIds);
+
+        if (clear) {
+            await this.actionDispatcher.dispatch(SelectAllAction.create(false));
+        }
+        if (resolvedSelected.length > 0 || resolvedDeselected.length > 0) {
+            await this.actionDispatcher.dispatch(
+                SelectAction.create({ selectedElementsIDs: resolvedSelected, deselectedElementsIDs: resolvedDeselected })
+            );
+        }
+
+        return this.success(this.summarize(resolvedSelected, resolvedDeselected, clear ?? false), {
+            selectedElementIds: this.encodeIds(resolvedSelected),
+            deselectedElementIds: this.encodeIds(resolvedDeselected),
+            cleared: clear ?? false
+        });
+    }
+
+    protected summarize(selected: string[], deselected: string[], cleared: boolean): string {
+        const parts: string[] = [];
+        if (cleared) parts.push('Cleared previous selection.');
+        if (selected.length > 0) parts.push(`Selected ${selected.length} element${selected.length === 1 ? '' : 's'}.`);
+        if (deselected.length > 0) parts.push(`Deselected ${deselected.length} element${deselected.length === 1 ? '' : 's'}.`);
+        return parts.length > 0 ? parts.join(' ') : 'Selection unchanged.';
+    }
+}

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

@@ -0,0 +1,162 @@
+/********************************************************************************
+ * 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,
+    CenterAction,
+    FitToScreenAction,
+    GetViewportAction,
+    OriginViewportAction,
+    Point,
+    SetViewportAction
+} from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import {
+    McpDiagramScopedInputSchema,
+    AbstractMcpDiagramToolHandler,
+    McpToolError,
+    McpToolResult,
+    elementIds,
+    position,
+    requestActionOrFail
+} from '../../server';
+
+export const VIEWPORT_ACTIONS = ['fit-to-screen', 'center-on-elements', 'reset-viewport', 'set-viewport'] as const;
+export type ViewportAction = (typeof VIEWPORT_ACTIONS)[number];
+
+export const SetViewInputSchema = McpDiagramScopedInputSchema.extend({
+    action: z.enum(VIEWPORT_ACTIONS).describe('The type of viewport change action to be undertaken.'),
+    elementIds: elementIds
+        .optional()
+        .describe(
+            "Elements to center on or fit (relevant for 'center-on-elements' and 'fit-to-screen'). Omit to target the whole diagram."
+        ),
+    zoom: z
+        .number()
+        .min(0.05)
+        .max(20)
+        .optional()
+        .describe(
+            "Absolute zoom level for `action: 'set-viewport'` (range 0.05..20, where 1 is 100% / native scale). " +
+                'Ignored by other actions. Omit to keep the current zoom while changing scroll.'
+        ),
+    scroll: position
+        .optional()
+        .describe(
+            "Absolute scroll position for `action: 'set-viewport'`, in diagram coordinates (top-left of the visible area). " +
+                'Ignored by other actions. Omit to keep the current scroll while changing zoom.'
+        )
+});
+export type SetViewInput = z.infer<typeof SetViewInputSchema>;
+
+export const SetViewOutputSchema = z.object({
+    action: z.enum(VIEWPORT_ACTIONS).describe('Echo of the viewport action that was applied.'),
+    targetIds: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "Aliased ids the action targeted (resolved from input or fall-back of all elements). Omitted for `'set-viewport'` since that action targets coordinates, not elements."
+        ),
+    viewport: z
+        .object({
+            scroll: position,
+            zoom: z.number()
+        })
+        .optional()
+        .describe("Resolved final viewport when `action: 'set-viewport'` was applied (current values merged with the supplied overrides).")
+});
+
+@injectable()
+export class SetViewMcpToolHandler extends AbstractMcpDiagramToolHandler<SetViewInput> {
+    /** Timeout (in ms) for the `GetViewportAction` round-trip used by `set-viewport` partial updates. Override via subclass + rebind. */
+    protected readonly viewportQueryTimeoutMs: number = 5000;
+
+    static readonly NAME = 'set-view';
+    readonly name = SetViewMcpToolHandler.NAME;
+    override readonly title = 'Set Diagram Viewport';
+    readonly description =
+        "Set the viewport of the session's associated UI client to focus the user's attention. " +
+        '`fit-to-screen` zooms+pans so all elements (or the listed `elementIds`) are visible; ' +
+        '`center-on-elements` pans without changing zoom, useful to highlight a specific element after creating or modifying it; ' +
+        '`reset-viewport` returns the camera to the origin at default zoom; ' +
+        '`set-viewport` applies an explicit `zoom` and/or `scroll` (omit either to preserve its current value). ' +
+        'Only invoke on explicit user request or when the user clearly benefits from a viewport nudge ' +
+        '(e.g. just created an element off-screen). Note this changes client-side viewport state but not the model.';
+    readonly inputSchema = SetViewInputSchema;
+    override readonly outputSchema = SetViewOutputSchema;
+    /** Viewport IS client-side environment; dispatching mutates it, so the read-base default doesn't honestly apply. */
+    override readonly readOnlyHint = false;
+
+    @inject(ActionDispatcher) protected actionDispatcher: ActionDispatcher;
+
+    protected async createResult({ action, elementIds, zoom, scroll }: SetViewInput): Promise<McpToolResult> {
+        if (action === 'set-viewport') {
+            return this.applyExplicitViewport(zoom, scroll);
+        }
+        const resolvedIds = elementIds ? elementIds.map(id => this.aliasService.lookup(id)) : this.modelState.index.allIds();
+        const dispatchAction = this.buildIntentAction(action, resolvedIds);
+        await this.actionDispatcher.dispatch(dispatchAction);
+        return this.success('Viewport successfully changed', { action, targetIds: this.encodeIds(resolvedIds) });
+    }
+
+    /**
+     * Map an intent-driven viewport action (`fit-to-screen`, `center-on-elements`,
+     * `reset-viewport`) to the matching sprotty action. The exhaustive switch lets TypeScript
+     * narrow the remaining `'set-viewport'` case out at compile time, so we don't need a
+     * runtime guard.
+     */
+    protected buildIntentAction(action: Exclude<ViewportAction, 'set-viewport'>, resolvedIds: string[]): Action {
+        switch (action) {
+            case 'fit-to-screen':
+                return FitToScreenAction.create(resolvedIds, { animate: true, padding: 20 });
+            case 'center-on-elements':
+                return CenterAction.create(resolvedIds, { animate: true, retainZoom: true });
+            case 'reset-viewport':
+                return OriginViewportAction.create({ animate: true });
+        }
+    }
+
+    /**
+     * Build the merged viewport for `set-viewport`: query the current viewport from the client,
+     * overlay the caller's `zoom` / `scroll` overrides, dispatch a {@link SetViewportAction}.
+     * Querying lets the LLM specify only one axis of change — the other is preserved instead of
+     * snapping to a placeholder default.
+     */
+    protected async applyExplicitViewport(zoom: number | undefined, scroll: Point | undefined): Promise<McpToolResult> {
+        if (zoom === undefined && scroll === undefined) {
+            throw new McpToolError("'set-viewport' requires at least one of `zoom` or `scroll`.");
+        }
+        const rootId = this.modelState.root.id;
+        const current = await requestActionOrFail(
+            this.actionDispatcher,
+            GetViewportAction.create(),
+            this.viewportQueryTimeoutMs,
+            this.name
+        );
+        // Some clients respond before layout completes — fall back to origin / 1× when fields are null.
+        const newViewport = {
+            scroll: scroll ?? (Point.isValid(current.viewport.scroll) ? current.viewport.scroll : Point.ORIGIN),
+            zoom: zoom ?? (Number.isFinite(current.viewport.zoom) ? current.viewport.zoom : 1)
+        };
+        await this.actionDispatcher.dispatch(SetViewportAction.create(rootId, newViewport, { animate: true }));
+        return this.success(`Viewport set to scroll=(${newViewport.scroll.x}, ${newViewport.scroll.y}) zoom=${newViewport.zoom}`, {
+            action: 'set-viewport',
+            viewport: newViewport
+        });
+    }
+}

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

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * 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, UndoAction } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { McpDiagramScopedInputSchema, McpToolError, McpToolResult, OperationMcpDiagramToolHandler } from '../../server';
+
+export const UndoInputSchema = McpDiagramScopedInputSchema.extend({
+    commandsToUndo: z.number().min(1).default(1).describe('Number of commands to undo. Defaults to 1 (most recent command).')
+});
+export type UndoInput = z.infer<typeof UndoInputSchema>;
+
+export const UndoOutputSchema = z.object({
+    commandsUndone: z.number().int().describe('Number of commands actually reverted.')
+});
+
+/**
+ * Undo a given number of the most recent actions on the command stack.
+ */
+@injectable()
+export class UndoMcpToolHandler extends OperationMcpDiagramToolHandler<UndoInput> {
+    static readonly NAME = 'undo';
+    readonly name = UndoMcpToolHandler.NAME;
+    override readonly title = 'Undo Diagram Commands';
+    readonly description =
+        "Undo recent commands on the diagram's command stack. " +
+        'Defaults to undoing one command — the most recent operation — when `commandsToUndo` is omitted. ' +
+        'Note that some tools dispatch multiple commands per call (e.g. `create-nodes` typically dispatches a node + a label command); ' +
+        'check the previous tool result for the exact count if you need to reverse more than the last one. ' +
+        "Throws when there's nothing on the undo stack. Only do this on an explicit user request.";
+    readonly inputSchema = UndoInputSchema;
+    override readonly outputSchema = UndoOutputSchema;
+
+    @inject(CommandStack) protected commandStack: CommandStack;
+
+    protected async createResult({ commandsToUndo }: UndoInput): Promise<McpToolResult> {
+        if (!this.commandStack.canUndo()) {
+            throw new McpToolError('Nothing to undo (undo stack is empty; the model is at its initial state for this session).');
+        }
+
+        for (let i = 0; i < commandsToUndo; i++) {
+            await this.actionDispatcher.dispatch(UndoAction.create());
+        }
+
+        return this.success('Undo successful', { commandsUndone: commandsToUndo });
+    }
+}

package/src/tools/index.ts

@@ -0,0 +1,34 @@
+/********************************************************************************
+ * 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/count-elements-mcp-tool-handler';
+export * from './handlers/create-edges-mcp-tool-handler';
+export * from './handlers/create-nodes-mcp-tool-handler';
+export * from './handlers/delete-elements-mcp-tool-handler';
+export * from './handlers/diagram-model-mcp-tool-handler';
+export * from './handlers/element-types-mcp-tool-handler';
+export * from './handlers/get-selection-mcp-tool-handler';
+export * from './handlers/layout-mcp-tool-handler';
+export * from './handlers/modify-edges-mcp-tool-handler';
+export * from './handlers/modify-nodes-mcp-tool-handler';
+export * from './handlers/query-elements-mcp-tool-handler';
+export * from './handlers/redo-mcp-tool-handler';
+export * from './handlers/save-model-mcp-tool-handler';
+export * from './handlers/session-info-mcp-tool-handler';
+export * from './handlers/set-selection-mcp-tool-handler';
+export * from './handlers/set-view-mcp-tool-handler';
+export * from './handlers/undo-mcp-tool-handler';
+export * from './handlers/validate-diagram-mcp-tool-handler';

package/src/tools/tool-annotations.spec.ts

@@ -0,0 +1,141 @@
+/********************************************************************************
+ * 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 { expect } from 'chai';
+import { interfaces } from 'inversify';
+import { SetViewMcpToolHandler } from './handlers/set-view-mcp-tool-handler';
+import { CreateEdgesMcpToolHandler } from './handlers/create-edges-mcp-tool-handler';
+import { CreateNodesMcpToolHandler } from './handlers/create-nodes-mcp-tool-handler';
+import { DeleteElementsMcpToolHandler } from './handlers/delete-elements-mcp-tool-handler';
+import { QueryElementsMcpToolHandler } from './handlers/query-elements-mcp-tool-handler';
+import { GetSelectionMcpToolHandler } from './handlers/get-selection-mcp-tool-handler';
+import { ModifyEdgesMcpToolHandler } from './handlers/modify-edges-mcp-tool-handler';
+import { ModifyNodesMcpToolHandler } from './handlers/modify-nodes-mcp-tool-handler';
+import { RedoMcpToolHandler } from './handlers/redo-mcp-tool-handler';
+import { SaveModelMcpToolHandler } from './handlers/save-model-mcp-tool-handler';
+import { UndoMcpToolHandler } from './handlers/undo-mcp-tool-handler';
+import { ValidateDiagramMcpToolHandler } from './handlers/validate-diagram-mcp-tool-handler';
+
+interface AnnotatedHandler {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+
+/**
+ * Reads the four annotation hint fields off a freshly `new`-ed handler. Mirrors how the launcher
+ * reads metadata via `new Constructor()` at MCP-session-init (see
+ * `mcp-server-launcher.ts#registerDiagramScopeTools`); no DI wiring needed because the fields
+ * are plain class properties with literal initializers.
+ */
+function hintsOf(Constructor: interfaces.Newable<AnnotatedHandler>): AnnotatedHandler {
+    const handler = new Constructor();
+    return {
+        readOnlyHint: handler.readOnlyHint,
+        destructiveHint: handler.destructiveHint,
+        idempotentHint: handler.idempotentHint,
+        openWorldHint: handler.openWorldHint
+    };
+}
+
+const READ_DEFAULT: AnnotatedHandler = {
+    readOnlyHint: true,
+    destructiveHint: undefined,
+    idempotentHint: undefined,
+    openWorldHint: false
+};
+
+const OPERATION_DEFAULT: AnnotatedHandler = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+};
+
+describe('Tool annotations · per-handler matrix', () => {
+    describe('read-style handlers (inherit base default)', () => {
+        const readStyleHandlers: Array<[string, interfaces.Newable<AnnotatedHandler>]> = [
+            ['query-elements', QueryElementsMcpToolHandler],
+            ['get-selection', GetSelectionMcpToolHandler],
+            ['validate-diagram', ValidateDiagramMcpToolHandler]
+        ];
+        readStyleHandlers.forEach(([name, Constructor]) => {
+            it(`${name} matches the read-style default`, () => {
+                expect(hintsOf(Constructor)).to.deep.equal(READ_DEFAULT);
+            });
+        });
+    });
+
+    describe('operation-style handlers (override to write defaults)', () => {
+        const operationStyleHandlers: Array<[string, interfaces.Newable<AnnotatedHandler>]> = [
+            ['create-nodes', CreateNodesMcpToolHandler],
+            ['create-edges', CreateEdgesMcpToolHandler],
+            ['modify-nodes', ModifyNodesMcpToolHandler],
+            ['modify-edges', ModifyEdgesMcpToolHandler],
+            ['undo', UndoMcpToolHandler],
+            ['redo', RedoMcpToolHandler]
+        ];
+        operationStyleHandlers.forEach(([name, Constructor]) => {
+            it(`${name} matches the operation-style default`, () => {
+                expect(hintsOf(Constructor)).to.deep.equal(OPERATION_DEFAULT);
+            });
+        });
+    });
+
+    describe('per-handler overrides', () => {
+        it('delete-elements is destructiveHint:true (single-flag override)', () => {
+            expect(hintsOf(DeleteElementsMcpToolHandler)).to.deep.equal({ ...OPERATION_DEFAULT, destructiveHint: true });
+        });
+
+        it('save-model is NOT readOnly (writes to disk) and NOT destructive (creative)', () => {
+            // Spec: `readOnlyHint` means "does not modify its environment" — disk IS environment.
+            // `destructiveHint` is for irreversible deletion / data loss; save is creative.
+            // Save-model extends the read base (not the operation base) because it doesn't
+            // dispatch a model-mutating Operation, but we override the flat fields explicitly.
+            expect(hintsOf(SaveModelMcpToolHandler)).to.deep.equal({
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: false
+            });
+        });
+
+        it('set-view drops the read-only claim (viewport IS environment)', () => {
+            // Inherits from the read base, which would claim readOnlyHint:true. Override flips
+            // it: dispatching a viewport action mutates client-side state, even though no
+            // diagram model bytes change.
+            expect(hintsOf(SetViewMcpToolHandler)).to.deep.equal({
+                readOnlyHint: false,
+                destructiveHint: undefined,
+                idempotentHint: undefined,
+                openWorldHint: false
+            });
+        });
+    });
+
+    describe('toRegistrationConfig() assembles the annotations object the SDK expects', () => {
+        it('aggregates the flat fields into the SDK ToolAnnotations shape', () => {
+            const config = new DeleteElementsMcpToolHandler().toRegistrationConfig();
+            expect(config.annotations).to.deep.equal({
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: false,
+                openWorldHint: false
+            });
+        });
+    });
+});

package/src/util/index.ts

@@ -0,0 +1,18 @@
+/********************************************************************************
+ * 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 './markdown-util';
+export * from './mcp-util';

package/src/util/markdown-util.ts

@@ -0,0 +1,44 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * This function serializes a given array of objects into a Markdown table string.
+ */
+export function objectArrayToMarkdownTable(data: Record<string, any>[]): string {
+    if (!data.length) {
+        return '';
+    }
+
+    const headers = Object.keys(data[0]);
+    const headerRow = `| ${headers.join(' | ')} |`;
+    const separatorRow = `| ${headers.map(() => '---').join(' | ')} |`;
+
+    const dataRows = data.map((obj: Record<string, any>) => {
+        const rowString = headers
+            .map(header => {
+                const value = obj[header] ?? '';
+                if (typeof value === 'object') {
+                    return JSON.stringify(value).replace(/["{}|]/g, '');
+                }
+                // Escape pipe characters in scalar values so they don't break the table layout
+                return String(value).replace(/\|/g, '\\|');
+            })
+            .join(' | ');
+        return `| ${rowString} |`;
+    });
+
+    return [headerRow, separatorRow, ...dataRows].join('\n');
+}

package/src/util/mcp-util.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * Copyright (c) 2025-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
+ ********************************************************************************/
+
+/**
+ * Formats a list of per-input notices (errors, warnings, …) as a Markdown bullet list with a
+ * leading heading. Returns an empty string when `notices` is empty so callers can append
+ * unconditionally.
+ */
+export function formatNoticeList(kind: string, notices: string[]): string {
+    if (notices.length === 0) return '';
+    return `\nThe following ${kind} occurred:\n${notices.map(notice => `- ${notice}`).join('\n')}`;
+}