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

package/lib/util/markdown-util.d.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
+ ********************************************************************************/
+/**
+ * This function serializes a given array of objects into a Markdown table string.
+ */
+export declare function objectArrayToMarkdownTable(data: Record<string, any>[]): string;
+//# sourceMappingURL=markdown-util.d.ts.map

package/lib/util/markdown-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-util.d.ts","sourceRoot":"","sources":["../../src/util/markdown-util.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;kFAckF;AAElF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,MAAM,CAwB9E"}

package/lib/util/markdown-util.js

@@ -0,0 +1,45 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.objectArrayToMarkdownTable = objectArrayToMarkdownTable;
+/**
+ * This function serializes a given array of objects into a Markdown table string.
+ */
+function objectArrayToMarkdownTable(data) {
+    if (!data.length) {
+        return '';
+    }
+    const headers = Object.keys(data[0]);
+    const headerRow = `| ${headers.join(' | ')} |`;
+    const separatorRow = `| ${headers.map(() => '---').join(' | ')} |`;
+    const dataRows = data.map((obj) => {
+        const rowString = headers
+            .map(header => {
+            var _a;
+            const value = (_a = obj[header]) !== null && _a !== void 0 ? _a : '';
+            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');
+}
+//# sourceMappingURL=markdown-util.js.map

package/lib/util/markdown-util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-util.js","sourceRoot":"","sources":["../../src/util/markdown-util.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;kFAckF;;AAKlF,gEAwBC;AA3BD;;GAEG;AACH,SAAgB,0BAA0B,CAAC,IAA2B;IAClE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,SAAS,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAC/C,MAAM,YAAY,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAEnE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAwB,EAAE,EAAE;QACnD,MAAM,SAAS,GAAG,OAAO;aACpB,GAAG,CAAC,MAAM,CAAC,EAAE;;YACV,MAAM,KAAK,GAAG,MAAA,GAAG,CAAC,MAAM,CAAC,mCAAI,EAAE,CAAC;YAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC5B,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,+EAA+E;YAC/E,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC/C,CAAC,CAAC;aACD,IAAI,CAAC,KAAK,CAAC,CAAC;QACjB,OAAO,KAAK,SAAS,IAAI,CAAC;IAC9B,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC"}

package/lib/util/mcp-util.d.ts

@@ -0,0 +1,22 @@
+/********************************************************************************
+ * 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 declare function formatNoticeList(kind: string, notices: string[]): string;
+//# sourceMappingURL=mcp-util.d.ts.map

package/lib/util/mcp-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-util.d.ts","sourceRoot":"","sources":["../../src/util/mcp-util.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;kFAckF;AAElF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAGxE"}

package/lib/util/mcp-util.js

@@ -0,0 +1,29 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatNoticeList = formatNoticeList;
+/**
+ * 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.
+ */
+function formatNoticeList(kind, notices) {
+    if (notices.length === 0)
+        return '';
+    return `\nThe following ${kind} occurred:\n${notices.map(notice => `- ${notice}`).join('\n')}`;
+}
+//# sourceMappingURL=mcp-util.js.map

package/lib/util/mcp-util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-util.js","sourceRoot":"","sources":["../../src/util/mcp-util.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;kFAckF;;AAOlF,4CAGC;AARD;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,IAAY,EAAE,OAAiB;IAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,OAAO,mBAAmB,IAAI,eAAe,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACnG,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@eclipse-glsp/server-mcp",
+  "version": "2.7.0-next.9+a58ea45",
+  "description": "Extension of the GLSP Node Server for the Model Context Protocol",
+  "keywords": [
+    "eclipse",
+    "graphics",
+    "diagram",
+    "modeling",
+    "visualization",
+    "glsp",
+    "diagram editor",
+    "mcp"
+  ],
+  "homepage": "https://www.eclipse.org/glsp/",
+  "bugs": "https://github.com/eclipse-glsp/glsp/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-glsp/glsp-server-node.git"
+  },
+  "license": "(EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0)",
+  "author": {
+    "name": "Eclipse GLSP"
+  },
+  "contributors": [
+    {
+      "name": "Eclipse GLSP Project",
+      "email": "glsp-dev@eclipse.org",
+      "url": "https://projects.eclipse.org/projects/ecd.glsp"
+    }
+  ],
+  "main": "lib/index",
+  "types": "lib/index",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf lib *.tsbuildinfo coverage .nyc_output",
+    "generate:index": "glsp generateIndex src -f -s",
+    "lint": "eslint --ext .ts,.tsx ./src",
+    "test": "mocha --config ../../.mocharc \"./src/**/*.spec.?(ts|tsx)\"",
+    "test:ci": "yarn test --reporter mocha-ctrf-json-reporter",
+    "test:coverage": "nyc yarn test",
+    "watch": "tsc -w"
+  },
+  "dependencies": {
+    "@eclipse-glsp/server": "2.7.0-next.9+a58ea45",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6"
+  },
+  "peerDependencies": {
+    "inversify": "^6.1.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "a58ea45de80be3d2fcf46e0934af141b213f6187"
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export * from './prompts';
+export * from './resources';
+export * from './server';
+export * from './tools';
+export * from './util';
+// Module classes — exported here (not from `./server`) to avoid circular imports through
+// the handler barrels which the modules consume.
+export * from './server/mcp-diagram-module';
+export * from './server/mcp-server-module';

package/src/prompts/handlers/describe-diagram-mcp-prompt-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 { ClientSessionManager } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { AbstractMcpPromptHandler, McpPromptResult, resolveActiveSessionId } from '../../server';
+import {
+    CountElementsMcpToolHandler,
+    DiagramModelMcpToolHandler,
+    ElementTypesMcpToolHandler,
+    QueryElementsMcpToolHandler,
+    SetSelectionMcpToolHandler,
+    SetViewMcpToolHandler
+} from '../../tools';
+
+export const DescribeDiagramArgsSchema = z.object({
+    sessionId: z
+        .string()
+        .optional()
+        .describe('GLSP client session id (open diagram). Defaults to the only open session; required when multiple are open.')
+});
+export type DescribeDiagramArgs = z.infer<typeof DescribeDiagramArgsSchema>;
+
+/**
+ * Prompt template that instructs the agent to produce a structured description of a diagram.
+ * Pre-baked starting point invokable from the MCP-client UI; the agent then orchestrates the
+ * necessary tool calls on its own.
+ *
+ * Server-scope on purpose — the prompt itself has no per-session state, so we avoid forcing
+ * the user to type a sessionId in the common single-diagram case.
+ */
+@injectable()
+export class DescribeDiagramMcpPromptHandler extends AbstractMcpPromptHandler<DescribeDiagramArgs> {
+    static readonly NAME = 'describe-diagram';
+    readonly name = DescribeDiagramMcpPromptHandler.NAME;
+    override readonly title = 'Describe Diagram';
+    readonly description =
+        'Produce a structured, skim-friendly description of an open diagram. ' +
+        'The agent picks the right tools to gather data (overview, element-type breakdown, structure, notable elements) ' +
+        'and writes the description in its own words. ' +
+        'Use this as a starting point when the user asks "what does this diagram show?" or wants a documentation-style summary. ' +
+        '`sessionId` is optional — defaults to the only open session.';
+    readonly argsSchema = DescribeDiagramArgsSchema;
+
+    @inject(ClientSessionManager) protected clientSessionManager: ClientSessionManager;
+
+    override referencedToolNames(): string[] {
+        return [
+            CountElementsMcpToolHandler.NAME,
+            ElementTypesMcpToolHandler.NAME,
+            DiagramModelMcpToolHandler.NAME,
+            QueryElementsMcpToolHandler.NAME,
+            SetSelectionMcpToolHandler.NAME,
+            SetViewMcpToolHandler.NAME
+        ];
+    }
+
+    protected createResult(args: DescribeDiagramArgs): McpPromptResult {
+        const sessionId = resolveActiveSessionId(this.clientSessionManager, args.sessionId);
+        const text =
+            `Describe the diagram for session \`${sessionId}\`. Include:\n\n` +
+            `1. **Overview** — diagram type and total element count (use \`${CountElementsMcpToolHandler.NAME}\`).\n` +
+            `2. **Element-type breakdown** — what kinds of elements are present and how many of each ` +
+            `(use \`${ElementTypesMcpToolHandler.NAME}\` and \`${CountElementsMcpToolHandler.NAME}\`).\n` +
+            `3. **Structure** — load the model with \`${DiagramModelMcpToolHandler.NAME}\` and summarize the ` +
+            `hierarchy and major connections.\n` +
+            `4. **Notable elements** — call out anything that stands out (unconnected nodes, deeply ` +
+            `nested groups, missing labels). Use \`${QueryElementsMcpToolHandler.NAME}\` to locate specific cases.\n\n` +
+            `Keep the description concise and skim-friendly. ` +
+            `When mentioning an element, prefer its label or type, with the alias appended in parens — e.g. ` +
+            `"the 'Brew' task (#7)" or "the decision node (#9)" — never the bare alias alone, since aliases mean nothing to the user. ` +
+            `Use \`${SetSelectionMcpToolHandler.NAME}\` or \`${SetViewMcpToolHandler.NAME} → 'center-on-elements'\` to draw the user's attention.`;
+        return { messages: [{ role: 'user', content: { type: 'text', text } }] };
+    }
+}

package/src/prompts/handlers/suggest-improvements-mcp-prompt-handler.ts

@@ -0,0 +1,86 @@
+/********************************************************************************
+ * 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 { inject, injectable } from 'inversify';
+import * as z from 'zod/v4';
+import { AbstractMcpPromptHandler, McpPromptResult, resolveActiveSessionId } from '../../server';
+import {
+    DiagramModelMcpToolHandler,
+    QueryElementsMcpToolHandler,
+    SetSelectionMcpToolHandler,
+    ValidateDiagramMcpToolHandler
+} from '../../tools';
+
+export const SuggestImprovementsArgsSchema = z.object({
+    sessionId: z
+        .string()
+        .optional()
+        .describe('GLSP client session id (open diagram). Defaults to the only open session; required when multiple are open.')
+});
+export type SuggestImprovementsArgs = z.infer<typeof SuggestImprovementsArgsSchema>;
+
+/**
+ * Prompt template that asks the agent to review the diagram and propose concrete improvements
+ * (validation issues, structural smells, missing labels, etc.). The agent orchestrates the
+ * tool calls; this prompt only frames the task.
+ *
+ * Server-scope on purpose — the prompt itself has no per-session state, so we avoid forcing
+ * the user to type a sessionId in the common single-diagram case.
+ */
+@injectable()
+export class SuggestImprovementsMcpPromptHandler extends AbstractMcpPromptHandler<SuggestImprovementsArgs> {
+    static readonly NAME = 'suggest-improvements';
+    readonly name = SuggestImprovementsMcpPromptHandler.NAME;
+    override readonly title = 'Suggest Diagram Improvements';
+    readonly description =
+        'Review an open diagram and propose concrete improvements grouped by severity ' +
+        '(must-fix vs. nice-to-have). The agent runs validation, checks connectivity, looks for unclear labels, ' +
+        'and flags structural inconsistencies, then names the specific element ids for each suggestion so the user ' +
+        'can act on them. Read-only by intent — the prompt instructs the agent not to modify the diagram, only propose. ' +
+        '`sessionId` is optional — defaults to the only open session.';
+    readonly argsSchema = SuggestImprovementsArgsSchema;
+
+    @inject(ClientSessionManager) protected clientSessionManager: ClientSessionManager;
+
+    override referencedToolNames(): string[] {
+        return [
+            ValidateDiagramMcpToolHandler.NAME,
+            DiagramModelMcpToolHandler.NAME,
+            QueryElementsMcpToolHandler.NAME,
+            SetSelectionMcpToolHandler.NAME
+        ];
+    }
+
+    protected createResult(args: SuggestImprovementsArgs): McpPromptResult {
+        const sessionId = resolveActiveSessionId(this.clientSessionManager, args.sessionId);
+        const text =
+            `Review the diagram for session \`${sessionId}\` and propose concrete improvements. Focus on:\n\n` +
+            `1. **Validation issues** — run \`${ValidateDiagramMcpToolHandler.NAME}\` and surface any markers.\n` +
+            `2. **Connectivity** — load the model (\`${DiagramModelMcpToolHandler.NAME}\`) and flag unconnected ` +
+            `nodes or orphaned subgraphs.\n` +
+            `3. **Labelling** — use \`${QueryElementsMcpToolHandler.NAME}\` to find nodes that lack a meaningful ` +
+            `label, and edges with missing or unclear text.\n` +
+            `4. **Structure** — call out elements whose type or placement looks inconsistent with ` +
+            `the rest of the diagram.\n\n` +
+            `Group findings by severity (must-fix vs. nice-to-have). ` +
+            `When naming elements, prefer their label or type with the alias in parens — e.g. ` +
+            `"the 'Brew' task (#7)" or "the decision node (#9)" — never the bare alias alone, since aliases mean nothing to the user. ` +
+            `Point at each suggestion via \`${SetSelectionMcpToolHandler.NAME}\` so the user can navigate. ` +
+            `Do not modify the diagram — only propose.`;
+        return { messages: [{ role: 'user', content: { type: 'text', text } }] };
+    }
+}

package/src/prompts/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 './handlers/describe-diagram-mcp-prompt-handler';
+export * from './handlers/suggest-improvements-mcp-prompt-handler';

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

@@ -0,0 +1,181 @@
+/********************************************************************************
+ * 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, isGBoundsAware, 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 DiagramPngInputSchema = McpDiagramScopedInputSchema.extend({
+    scale: z
+        .number()
+        .min(0.1)
+        .max(4)
+        .optional()
+        .describe(
+            "Multiplier applied to the diagram's natural extent (range 0.1..4). Use values >1 for " +
+                'sharper-than-default renders, <1 for thumbnails. Ignored when `width` or `height` is supplied.'
+        ),
+    width: z
+        .number()
+        .int()
+        .min(1)
+        .max(8192)
+        .optional()
+        .describe('Override the rendered width in pixels. When given alone, the height is derived from the diagram aspect ratio.'),
+    height: z
+        .number()
+        .int()
+        .min(1)
+        .max(8192)
+        .optional()
+        .describe('Override the rendered height in pixels. When given alone, the width is derived from the diagram aspect ratio.'),
+    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 DiagramPngInput = z.infer<typeof DiagramPngInputSchema>;
+
+/** Rendering lives on the client — `RequestExportAction('png')` routes to the registered PNG exporter, which returns base64 via `ExportResultAction`. */
+@injectable()
+export class DiagramPngMcpResourceHandler extends AbstractMcpDiagramResourceHandler<DiagramPngInput> {
+    /** Default timeout (in ms) used when the call doesn't override `timeoutMs`. Override via subclass + rebind. */
+    protected readonly defaultTimeoutMs: number = 5000;
+
+    /**
+     * Default `scale` multiplier when the caller doesn't pin `width`/`height`/`scale`. `1` means
+     * "render at the diagram's natural extent" — sharp because the client rasterises the SVG
+     * at the requested size. Adopters override (e.g. to `2` for a high-DPI deployment) via
+     * subclass + rebind.
+     */
+    protected readonly defaultScale: number = 1;
+
+    static readonly NAME = 'diagram-png';
+    readonly name = DiagramPngMcpResourceHandler.NAME;
+    override readonly title = 'Diagram Model PNG';
+    readonly description =
+        'Render the session diagram as a base64-encoded PNG screenshot of its current visible state. ' +
+        'Includes all nodes, edges, and their styling — useful when a visual answer would help the agent ' +
+        '(layout reasoning, confirming a recently-created element looks right, sharing the diagram with the user). ' +
+        "Defaults to a sharp render at the diagram's natural extent; pass `scale` to multiply, " +
+        'or `width`/`height` to pin specific dimensions. ' +
+        'Requires a connected frontend client to perform the render and is subject to a timeout if no response arrives. ' +
+        'For a structured-text view of the model use `diagram-model` instead; for vector output use `diagram-svg`.';
+    readonly mimeType: McpMimeType = 'image/png';
+    readonly uri: McpResourceUri = { template: 'glsp://diagrams/{sessionId}/png' };
+    /** 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;
+    // `lastModified` intentionally omitted: we have no cheap, accurate freshness signal for the
+    // rendered PNG (the model state doesn't track a "rendered at" timestamp), and a stale value
+    // would mislead clients.
+    override readonly toolAlternativeInputSchema = DiagramPngInputSchema;
+
+    @inject(McpProgressReporter) protected progress: McpProgressReporter;
+
+    @inject(ClientActionKinds) protected clientActionKinds: Set<string>;
+
+    /** Skip-bind when the GLSP client doesn't speak `RequestExportAction` — every read would otherwise time out. */
+    override canRegister(): boolean {
+        return this.clientActionKinds.has(RequestExportAction.KIND);
+    }
+
+    protected async createResult({ scale, width, height, timeoutMs }: DiagramPngInput): Promise<McpResourceContent> {
+        const resolved = this.resolveSize(scale, width, height);
+        // Best-effort beat for clients that opted in via `_meta.progressToken`; no-ops otherwise.
+        await this.progress.emit({ progress: 0, message: 'Awaiting client-side PNG render…' });
+        const response = await this.requestAction(
+            RequestExportAction.create('png', { formatOptions: { width: resolved.width, height: resolved.height } }),
+            timeoutMs ?? this.defaultTimeoutMs
+        );
+        // A misbehaving exporter strategy returning text-encoded data here would silently corrupt the blob; fail loudly instead.
+        if (response.encoding !== 'base64') {
+            throw new McpToolError(`PNG export returned unexpected encoding '${response.encoding}'; expected 'base64'.`);
+        }
+        return { blob: response.data };
+    }
+
+    /**
+     * Resolve the final render size with this precedence:
+     * - `width` and `height` both given → use as-is.
+     * - only one of `width`/`height` given → derive the other from the diagram aspect ratio.
+     * - neither dimension given → natural × (`scale` ?? {@link defaultScale}).
+     */
+    protected resolveSize(
+        scale: number | undefined,
+        width: number | undefined,
+        height: number | undefined
+    ): { width: number; height: number } {
+        if (width !== undefined && height !== undefined) {
+            return { width, height };
+        }
+        const natural = this.computeNaturalSize();
+        if (width !== undefined) {
+            return { width, height: Math.max(1, Math.round(width * (natural.height / natural.width))) };
+        }
+        if (height !== undefined) {
+            return { width: Math.max(1, Math.round(height * (natural.width / natural.height))), height };
+        }
+        const factor = scale ?? this.defaultScale;
+        return {
+            width: Math.max(1, Math.round(natural.width * factor)),
+            height: Math.max(1, Math.round(natural.height * factor))
+        };
+    }
+
+    /**
+     * Compute the diagram's natural extent as the bounding box of every {@link isGBoundsAware}
+     * element with both `position` and `size`. Throws when the model has no positioned elements
+     * — a 1×1 PNG of an empty diagram is technically renderable but useless, and surfacing it
+     * as a self-correctable error lets the LLM react (e.g. wait for layout, ask the user).
+     */
+    protected computeNaturalSize(): { width: number; height: number } {
+        let maxX = 0;
+        let maxY = 0;
+        for (const id of this.modelState.index.allIds()) {
+            const element = this.modelState.index.get(id);
+            if (!element || !isGBoundsAware(element)) {
+                continue;
+            }
+            const position = element.position;
+            const size = element.size;
+            if (position && size && size.width > 0 && size.height > 0) {
+                maxX = Math.max(maxX, position.x + size.width);
+                maxY = Math.max(maxY, position.y + size.height);
+            }
+        }
+        if (maxX <= 0 || maxY <= 0) {
+            throw new McpToolError(
+                'Diagram has no positioned elements yet — render once after layout completes, or pass `width` / `height` explicitly.'
+            );
+        }
+        return { width: Math.ceil(maxX), height: Math.ceil(maxY) };
+    }
+}