Add support for Model Context Protocol by martin-fleck-at · Pull Request #120 · eclipse-glsp/glsp-server-node

martin-fleck-at · 2025-12-18T19:34:14Z

What it does

Exposes each GLSP server as an MCP server over Streamable HTTP, so LLM
clients can query and mutate diagrams via MCP resources, tools, and
prompts.

Architecture

One MCP endpoint per GLSP server process; under per-window
deployment, one endpoint per application instance.
Auto-discovers diagram-scoped contributions from all GLSP client
sessions and merges them into a shared surface with cross-session
ID aliasing.
Pluggable model-serializer, label-provider, and element-types
extension points for diagram-specific overrides.
Opt-in: started only when configured on initialize.
Random port by default; the announced URL is surfaced for adopter
discovery.
No built-in auth; loopback-only unless explicitly acknowledged.
Targets MCP spec 2025-06-18 via the official SDK.

Adopters

Diagram module: register language-specific tools, prompts,
resources, and override the diagram extension points.
Server module: configure server-wide options (port, route, auth
acknowledgement).
The workflow server example wires both end-to-end.

Server framework

Adds an initialize-contribution extension point on the default
GLSP server, used by MCP to surface configuration on initialize.
The previous handleInitializeArgs hook is deprecated — adopters
subclassing the default server should migrate.

Documentation

Adopter README plus a separate architecture document covering the
feature matrix, lifecycle, extension points, and rationale.

Misc

Small fix to a base type-guard on edges in the graph package.
Disposes the server instance when the JSON-RPC client connection
closes uncleanly (browser/IDE force-close).
Action dispatcher drops stale response actions arriving without a
registered handler instead of throwing.

Part of eclipse-glsp/glsp#1546
Requires eclipse-glsp/glsp-client#456

How to test

Start the node server
Connect with a client that sets the mcpServer configuration
Read the actual url of the server out of the log, e.g., [McpServerManager] MCP server 'glspMcpServer' is ready to accept new client requests on: http://127.0.0.1:64577/glsp-mcp
Connect to the server using the Theia Integration (caution: no support for MCP Resources) or Claude Code or the MCP Inspector.
Test querying resources and tools

Follow-ups

Changelog

This PR should be mentioned in the changelog
This PR introduces a breaking change (if yes, provide more details below for the changelog and the migration guide)

Copilot

Pull request overview

This PR adds Model Context Protocol (MCP) support to the GLSP server, enabling AI assistants and other MCP clients to interact with GLSP diagrams through a standardized protocol. The implementation provides HTTP-based MCP server functionality with default tools for diagram manipulation and resources for querying diagram state.

Key changes:

Introduces new @eclipse-glsp/server-mcp package with MCP server infrastructure, HTTP transport layer, and default tools/resources for diagram interaction
Extends GLSP server initialization to support contributions via GLSPServerInitContribution interface
Updates workflow example to demonstrate MCP integration

Reviewed changes

Copilot reviewed 19 out of 21 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/server/src/common/session/client-session-manager.ts	Adds `getSessions()` method to retrieve all active client sessions
packages/server/src/common/protocol/glsp-server.ts	Introduces `GLSPServerInitContribution` mechanism and deprecates `handleInitializeArgs`
packages/server/src/common/di/server-module.ts	Adds binding configuration for `GLSPServerInitContribution`
packages/server-mcp/tsconfig.json	TypeScript configuration for new MCP package
packages/server-mcp/src/mcp-util.ts	Utility functions for MCP parameter extraction and result formatting
packages/server-mcp/src/mcp-server-manager.ts	Core MCP server lifecycle management and HTTP server initialization
packages/server-mcp/src/mcp-server-contribution.ts	Interface for extending MCP server with custom tools and resources
packages/server-mcp/src/index.ts	Package exports
packages/server-mcp/src/http-server-with-sessions.ts	HTTP server implementation with MCP session management
packages/server-mcp/src/di.config.ts	Dependency injection configuration for MCP module
packages/server-mcp/src/default-mcp-tool-contribution.ts	Default MCP tools for diagram validation, element creation, undo/redo, and save operations
packages/server-mcp/src/default-mcp-resource-contribution.ts	Default MCP resources for querying sessions, diagram types, element types, and models
packages/server-mcp/package.json	Package metadata and dependencies for MCP package
packages/server-mcp/.eslintrc.js	ESLint configuration ignoring MCP SDK imports
examples/workflow-server/tsconfig.json	Adds reference to server-mcp package
examples/workflow-server/src/node/app.ts	Integrates MCP module into workflow server
examples/workflow-server/src/common/workflow-glsp-server.ts	Migrates from deprecated `handleInitializeArgs` to `GLSPServerInitContribution`
examples/workflow-server/src/common/workflow-diagram-module.ts	Updates binding to use new init contribution pattern
examples/workflow-server/package.json	Adds dependency on server-mcp package

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Exposes each GLSP server as an MCP server over Streamable HTTP, so LLM clients can query and mutate diagrams via MCP resources, tools, and prompts. Architecture - One MCP endpoint per GLSP server process; under per-window deployment, one endpoint per application instance. - Auto-discovers diagram-scoped contributions from all GLSP client sessions and merges them into a shared surface with cross-session ID aliasing. - Pluggable model-serializer, label-provider, and element-types extension points for diagram-specific overrides. - Opt-in: started only when configured on initialize. - Random port by default; the announced URL is surfaced for adopter discovery. - No built-in auth; loopback-only unless explicitly acknowledged. - Targets MCP spec 2025-06-18 via the official SDK. Adopters - Diagram module: register language-specific tools, prompts, resources, and override the diagram extension points. - Server module: configure server-wide options (port, route, auth acknowledgement). - The workflow server example wires both end-to-end. Server framework - Adds an initialize-contribution extension point on the default GLSP server, used by MCP to surface configuration on initialize. The previous `handleInitializeArgs` hook is deprecated — adopters subclassing the default server should migrate. Documentation - Adopter README plus a separate architecture document covering the feature matrix, lifecycle, extension points, and rationale. Misc - Small fix to a base type-guard on edges in the graph package. - Disposes the server instance when the JSON-RPC client connection closes uncleanly (browser/IDE force-close). - Action dispatcher drops stale response actions arriving without a registered handler instead of throwing. Part of eclipse-glsp/glsp#1546 Co-authored-by: Andreas Hell <44035624+Sakrafux@users.noreply.github.com>

tortmayr

Thanks for the rework Martin.
In general the code looks good to me.
I have a couple of inline comments.

In addition, we should probably create follow-up issues for the following tasks

Java alignment/implementation. Not planned in yet from our side, but we should open the issue nevertheless for tracking. (tag with help wanted, looking for sponsor)
Once this is merged we should update the protocol doc on the website
It seems like we have a couple of concepts in place (initializers, factories) which sole purpose is to bypass inversify circular dependencies for contribution points. We should consider an alignmnet here and use the LazyInjector approach consistently (same as in client)

tortmayr · 2026-05-08T07:47:02Z

+
+    @inject(GLSPMcpServerFactory) protected glspMcpServerFactory: GLSPMcpServerFactory;
+
+    @inject(McpDiagramHandlerDispatcher) protected dispatcher: DefaultMcpDiagramHandlerDispatcher;


Weird mix of symbol injection and direct class typing.

Should probably create an interface for the McpDiagramHandlerDispatcher and use it here.

Alternatively, if you dont want to interface this consider renaming to McpDiagramHandlerDispatcher and directly using the class as service identifier

tortmayr · 2026-05-08T07:58:15Z

+            () =>
+                this.ping().catch(err => {
+                    if (!(err instanceof McpError) || err.code !== ErrorCode.RequestTimeout) {
+                        console.debug('MCP keep-alive ping failed:', err);


Consider injecting and using the logger here instead of plain console.log

tortmayr · 2026-05-08T07:59:43Z

        return new GLabelBuilder(GLabel)
            .type(ModelTypes.LABEL_HEADING)
-            .id(this.proxy.id + '_classname')
+            .id(this.proxy.id + '_label')


Question: Should we update the example1.wf file on the client side to reflect this change?
Or is is purely cosmetically?

The file is already correct, just the server was inconsistent. We can leave it I believe.

tortmayr · 2026-05-08T08:03:56Z

+    /** Best-effort fan-out — failures on individual MCP sessions (e.g. transport mid-close) are swallowed. */
+    protected broadcastResourceListChanged(): void {
+        for (const glspMcpServer of this.sessionServers.values()) {
+            glspMcpServer


SHould we directly expose this on the GLSPMcpServer TopLevel ?
Or is this a one time use, and we don't expect adopters to need the same functionality?

I wouldn't expect adopters to overwrite this tbh. we are the only caller and then we would also need to expose other similar methods. If you agree, I think wee should leave it as is.

tortmayr · 2026-05-08T08:10:47Z

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2022-2024 STMicroelectronics and others.
+ * Copyright (c) 2022-2026 STMicroelectronics and others.


Single header change with out additional file changes, is that correct?

tortmayr · 2026-05-11T08:57:22Z

+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import {


Double check comments, trim fluff.

tortmayr · 2026-05-11T08:58:54Z

+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import * as http from 'http';


Should be in a .spec.ts file. Otherwise it gets shipped as part of the source code

tortmayr · 2026-05-11T09:01:09Z

+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import { ApplyLabelEditOperation, CreateNodeOperation } from '@eclipse-glsp/server';


Should this file be tested as well?

tortmayr · 2026-05-11T09:03:32Z

    }
 }
+
+export namespace CreateNodeOperationHandler {


Place the namespace alongside the corresponding interface

tortmayr · 2026-05-11T09:05:05Z

+            try {
+                result = await initializer.initializeServer(this, params, result);
+            } catch (error: unknown) {
+                this.logger.error(`Error during server initialization from ${initializer.constructor.name}:`, error);


Catch without rethrow breaks promise resolution.
We catch all errors -> promise returned is never rejected

martin-fleck-at · 2026-05-12T07:42:58Z

Thanks for the rework Martin. In general the code looks good to me. I have a couple of inline comments.

Thank you very much, I'll address them shortly!

Java alignment/implementation. Not planned in yet from our side, but we should open the issue nevertheless for tracking. (tag with help wanted, looking for sponsor)
cf Add support for Model Context Protocol (MCP) in Java Server glsp#1672

Once this is merged we should update the protocol doc on the website
Good point! I added Update Protocol Documentation for Model Context Protocol (MCP) on Website glsp#1673 to track this officially.

It seems like we have a couple of concepts in place (initializers, factories) which sole purpose is to bypass inversify circular dependencies for contribution points. We should consider an alignmnet here and use the LazyInjector approach consistently (same as in client)

Do you have any particular places in mind that we introduced? I think we only have the registry initializers, similar to the ActionHandlerRegistryInitializer and OperationHandlerRegistryInitializer that already exist. And then we have a few factories similar to OperationHandlerFactory and ActionHandlerFactory. Or is that a more general comment to align long-term?

tortmayr · 2026-05-12T08:00:42Z

Do you have any particular places in mind that we introduced? I think we only have the registry initializers, similar to the ActionHandlerRegistryInitializer and OperationHandlerRegistryInitializer that already exist. And then we have a few factories similar to OperationHandlerFactory and ActionHandlerFactory. Or is that a more general comment to align long-term?

That was more a general comment to align long term. These concepts were introduced before the LazyInjector API was available. Now, it think it makes sense to align this and use one consistent approach for initializing contributions.

- McpHttpTransport.dispose: catch per-session close() rejections - McpDiagramHandlerDispatcher: extract interface - harvest: factor out getConstructorList helper + clarify JSDoc - dispatchStaticDiagramRead: clarify "pick first session" - DefaultGLSPMcpServer: inject Logger, drop console.debug - GShapeElement.is: drop; callers use `instanceof` - GEdge.is: deprecate; callers use `instanceof` - Move prompt-handler tests to resolveActiveSessionId spec - Add ElkLayoutModule (subclassable); keep factory wrapper - workflow-server: switch to new ElkLayoutModule

martin-fleck-at · 2026-05-12T08:44:09Z

I pushed a commit that hopefully addresses all your concerns.

@Unmanaged

- glsp-server: rethrow initializer error so initialize() rejects - glsp-mcp-server: redeclare picked methods; @Unmanaged ctor params - create-operation-handler: place namespaces alongside interfaces - ElementTypeEntry: trim header doc + add @experimental - mcp-model-serializer: drop stale alias-function note - mcp-resource-handler: trim header doc - mcp-server-launcher: trim dense JSDoc/inline comments - Rename dual-emit.spec → mcp-tool-handler.spec - Rename raw-http.test-util → raw-http.spec (drop tsconfig exclude) - Add create-nodes-mcp-tool-handler.spec (4 cases) - Revert incidental year bump on create-merge/decision-node-handler

tortmayr

LGTM! Thanks for the fast update.
👍🏼

martin-fleck-at requested review from Copilot and tortmayr December 18, 2025 19:34

Copilot AI reviewed Dec 18, 2025

View reviewed changes

Comment thread packages/server-mcp/src/http-server-with-sessions.ts Outdated

martin-fleck-at force-pushed the issues/1546 branch from fd94922 to 05c8fc5 Compare December 18, 2025 19:42

This was referenced Dec 19, 2025

Add support for Model Context Protocol eclipse-glsp/glsp-client#456

Merged

Add support for Model Context Protocol eclipse-glsp/glsp-theia-integration#271

Merged

Sakrafux mentioned this pull request Mar 25, 2026

Issues/1546 #127

Merged

martin-fleck-at force-pushed the issues/1546 branch from 84f5685 to 6fec69a Compare May 6, 2026 15:15

martin-fleck-at mentioned this pull request May 6, 2026

Add support for Model Context Protocol eclipse-glsp/glsp-vscode-integration#91

Merged

2 tasks

martin-fleck-at force-pushed the issues/1546 branch from 6fec69a to 98d9088 Compare May 8, 2026 09:47

tortmayr requested changes May 11, 2026

View reviewed changes

martin-fleck-at mentioned this pull request May 12, 2026

Update Protocol Documentation for Model Context Protocol (MCP) on Website eclipse-glsp/glsp#1673

Open

tortmayr self-requested a review May 12, 2026 15:51

tortmayr approved these changes May 12, 2026

View reviewed changes

martin-fleck-at merged commit a58ea45 into main May 12, 2026
5 checks passed

martin-fleck-at deleted the issues/1546 branch May 12, 2026 22:24


		@inject(GLSPMcpServerFactory) protected glspMcpServerFactory: GLSPMcpServerFactory;

		@inject(McpDiagramHandlerDispatcher) protected dispatcher: DefaultMcpDiagramHandlerDispatcher;

Conversation

martin-fleck-at commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What it does

How to test

Follow-ups

Changelog

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

tortmayr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martin-fleck-at commented May 12, 2026

Uh oh!

tortmayr commented May 12, 2026

Uh oh!

martin-fleck-at commented May 12, 2026

Uh oh!

tortmayr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

martin-fleck-at commented Dec 18, 2025 •

edited

Loading