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

package/src/server/mcp-progress-reporter.spec.ts

@@ -0,0 +1,93 @@
+/********************************************************************************
+ * 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 { ServerNotification } from '@modelcontextprotocol/sdk/types.js';
+import { expect } from 'chai';
+import { McpProgressReporter } from './mcp-progress-reporter';
+import { McpRequestExtra, mcpRequestContext } from './mcp-request-context';
+
+function buildExtra(progressToken?: string | number): { extra: McpRequestExtra; sent: ServerNotification[] } {
+    const sent: ServerNotification[] = [];
+    const extra = {
+        sendNotification: async (n: ServerNotification) => {
+            sent.push(n);
+        },
+        _meta: progressToken === undefined ? undefined : { progressToken }
+    } as unknown as McpRequestExtra;
+    return { extra, sent };
+}
+
+describe('McpProgressReporter', () => {
+    it('no-ops inside a request that has no progressToken (client did not opt in)', async () => {
+        const reporter = new McpProgressReporter();
+        const { extra, sent } = buildExtra(undefined);
+
+        await mcpRequestContext.run(extra, async () => {
+            await reporter.emit({ progress: 0, message: 'starting' });
+        });
+
+        expect(sent).to.have.lengthOf(0);
+    });
+
+    it('emits notifications/progress when the request carries a progressToken', async () => {
+        const reporter = new McpProgressReporter();
+        const { extra, sent } = buildExtra('tok-42');
+
+        await mcpRequestContext.run(extra, async () => {
+            await reporter.emit({ progress: 0, message: 'starting' });
+            await reporter.emit({ progress: 1, total: 3, message: 'step 1/3' });
+        });
+
+        expect(sent).to.have.lengthOf(2);
+        expect(sent[0]).to.deep.equal({
+            method: 'notifications/progress',
+            params: { progressToken: 'tok-42', progress: 0, message: 'starting' }
+        });
+        expect(sent[1]).to.deep.equal({
+            method: 'notifications/progress',
+            params: { progressToken: 'tok-42', progress: 1, total: 3, message: 'step 1/3' }
+        });
+    });
+
+    it('accepts numeric progress tokens', async () => {
+        const reporter = new McpProgressReporter();
+        const { extra, sent } = buildExtra(7);
+
+        await mcpRequestContext.run(extra, async () => {
+            await reporter.emit({ progress: 0 });
+        });
+
+        expect(sent).to.have.lengthOf(1);
+        expect(sent[0].params).to.deep.equal({ progressToken: 7, progress: 0 });
+    });
+
+    it('swallows transport failures so a broken send never breaks the producing tool', async () => {
+        const reporter = new McpProgressReporter();
+        const failingExtra = {
+            sendNotification: async () => {
+                throw new Error('transport closed');
+            },
+            _meta: { progressToken: 'tok-1' }
+        } as unknown as McpRequestExtra;
+
+        await mcpRequestContext.run(failingExtra, async () => {
+            // Must complete without throwing. If we re-threw, every PNG export would hard-fail
+            // when the client's SSE stream blipped — the opposite of progress reporting being
+            // a UX nicety.
+            await reporter.emit({ progress: 0, message: 'starting' });
+        });
+    });
+});

package/src/server/mcp-progress-reporter.ts

@@ -0,0 +1,67 @@
+/********************************************************************************
+ * 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 { injectable } from 'inversify';
+import { mcpRequestContext } from './mcp-request-context';
+
+/**
+ * Per-call shape of a `notifications/progress` emission. Mirrors the SDK's
+ * `ProgressNotificationParams` minus the `progressToken` field (the reporter pulls that from
+ * the active request context — the caller's job is just to describe the progress beat).
+ */
+export interface McpProgressBeat {
+    /** Monotonic progress count. Spec is loose; convention: increment from 0 toward `total` if known, or use seconds-elapsed otherwise. */
+    progress: number;
+    /** Total when known (e.g. number of nodes to process). Omit when bounded only by a timeout. */
+    total?: number;
+    /** Short user-facing description; surfaces in compatible clients' UI. */
+    message?: string;
+}
+
+/**
+ * Emits `notifications/progress` to the connected MCP client when the active request carries a
+ * `progressToken` in its `_meta`. Built on the same {@link mcpRequestContext} as
+ * {@link McpLogger}; handlers don't need to thread `extra` through their own signatures.
+ *
+ * Behaviour:
+ *  - Outside a request context (init, background): no-op.
+ *  - Inside a request context with no `progressToken` (client didn't opt in): no-op.
+ *    Universally supported per spec — clients that don't render progress simply omit the token.
+ *  - Failures to deliver are swallowed: a broken transport must not break the producing tool.
+ *
+ * Shared across MCP clients on the same GLSP session; per-client routing is handled by the
+ * active `mcpRequestContext` frame.
+ *
+ * @experimental
+ */
+@injectable()
+export class McpProgressReporter {
+    async emit(beat: McpProgressBeat): Promise<void> {
+        const extra = mcpRequestContext.getStore();
+        const progressToken = extra?._meta?.progressToken;
+        if (extra === undefined || progressToken === undefined) {
+            return;
+        }
+        try {
+            await extra.sendNotification({
+                method: 'notifications/progress',
+                params: { progressToken, ...beat }
+            });
+        } catch {
+            // Fire-and-forget — never propagate transport errors into tool execution.
+        }
+    }
+}

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

@@ -0,0 +1,157 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+import { ClientId, Logger, MaybePromise, ModelState } from '@eclipse-glsp/server';
+import { inject, injectable, interfaces } from 'inversify';
+import { ZodObject, ZodRawShape } from 'zod/v4';
+import { GLSPMcpServer } from './glsp-mcp-server';
+import { McpPromptResult, McpToolError, extractErrorMessage } from './mcp-handler-shared';
+import { McpIdAliasService } from './mcp-id-alias-service';
+import { McpDiagramScopedInput } from './mcp-input-schemas';
+import { mcpRequestContext } from './mcp-request-context';
+
+/**
+ * Multi-binding key for **server-scope** prompt handlers — singletons that don't target a
+ * specific GLSP client session. Diagram-scope prompts (one instance per open diagram) use the
+ * separate {@link McpDiagramPromptHandlerConstructor} multi-binding instead.
+ *
+ * Prompts are LLM-facing message templates the AI client may invoke. No prompts ship by default;
+ * the surface exists for adopters.
+ *
+ * @experimental
+ */
+export interface McpPromptHandler {
+    /** Prompt identifier exposed to the MCP client; matches the abstract base's field. */
+    readonly name: string;
+    registerPrompt(server: GLSPMcpServer): void;
+    /** Tool names this prompt's text references via `${OtherHandler.NAME}`; default: empty. */
+    referencedToolNames(): string[];
+}
+export const McpPromptHandler = Symbol('McpPromptHandler');
+
+/** Shared infrastructure for both server- and diagram-scope prompt handlers. */
+@injectable()
+abstract class BaseMcpPromptHandler {
+    @inject(Logger) protected logger: Logger;
+
+    /**
+     * Prompt identifier exposed to the MCP client. Also used to reference this prompt from
+     * other handlers' prompt or description text — wire via `static readonly NAME = '…'` and
+     * `readonly name = ClassName.NAME` so those cross-references survive renames.
+     */
+    abstract readonly name: string;
+    /** LLM-facing explanation surfaced in the prompt catalog. Keep concise — clients pass this verbatim to the model. */
+    abstract readonly description: string;
+    /** Adopter writes `z.object({ ... })`; the base passes `.shape` to the SDK. */
+    abstract readonly argsSchema: ZodObject<ZodRawShape>;
+    /** Optional human-friendly display name for UIs that render a friendlier label than `name`. */
+    readonly title?: string;
+
+    /** SDK-facing registration config; consumed by both registration paths. */
+    toRegistrationConfig(): { title?: string; description: string; argsSchema: ZodRawShape } {
+        return { title: this.title, description: this.description, argsSchema: this.argsSchema.shape };
+    }
+
+    /**
+     * Optional list of tool names this prompt's text refers to via `${OtherHandler.NAME}`
+     * substitutions. Default: empty. Override in concrete subclasses to declare references so
+     * the launcher can warn at registration time when an adopter unbinds a referenced tool —
+     * the prompt would otherwise still register and silently produce text pointing at a tool
+     * that no longer exists. Pure declarative metadata; never invoked at request time.
+     */
+    referencedToolNames(): string[] {
+        return [];
+    }
+
+    /**
+     * Catches `McpToolError` (→ surfaced as a `user`-role assistant message) and unexpected
+     * errors (→ logged + extracted message). Errors map to a single text-content message so
+     * the LLM sees the failure in the prompt response.
+     */
+    protected async execute(producer: () => MaybePromise<McpPromptResult>): Promise<McpPromptResult> {
+        try {
+            return await producer();
+        } catch (err: unknown) {
+            if (err instanceof McpToolError) {
+                return this.errorResult(err.message);
+            }
+            const message = extractErrorMessage(err);
+            this.logger.error(`Unexpected error in prompt '${this.name}': ${message}`, err);
+            return this.errorResult(message);
+        }
+    }
+
+    protected errorResult(message: string): McpPromptResult {
+        return { messages: [{ role: 'user', content: { type: 'text', text: message } }] };
+    }
+}
+
+/**
+ * Server-scope prompt base — for prompts that don't target a specific GLSP client session
+ * (e.g., a prompt that summarizes the system's state). Bound under {@link McpPromptHandler};
+ * the launcher invokes `registerPrompt(server)` once per MCP session.
+ *
+ * @experimental
+ */
+@injectable()
+export abstract class AbstractMcpPromptHandler<T = Record<string, unknown>> extends BaseMcpPromptHandler implements McpPromptHandler {
+    /** Throw {@link McpToolError} for expected errors; the base wraps. */
+    protected abstract createResult(args: T): MaybePromise<McpPromptResult>;
+
+    registerPrompt(server: GLSPMcpServer): void {
+        server.registerPrompt(this.name, this.toRegistrationConfig(), async (args, extra) =>
+            mcpRequestContext.run(extra, () => this.execute(() => this.createResult(args as T)))
+        );
+    }
+}
+
+/**
+ * Diagram-scope prompt base — for prompts whose argument schema carries a `sessionId`
+ * (e.g., a `describe-diagram` prompt for one open diagram).
+ *
+ * The launcher's dispatcher resolves `args.sessionId` to the right GLSP session and invokes
+ * {@link handle} on this session's per-instance handler. From the handler's perspective the
+ * session is implicit — `this.clientId`, `this.modelState`, `this.aliasService` (and any
+ * adopter `@inject(...)` fields) all resolve to that GLSP session's container.
+ *
+ * @experimental
+ */
+@injectable()
+export abstract class AbstractMcpDiagramPromptHandler<
+    T extends McpDiagramScopedInput = McpDiagramScopedInput
+> extends BaseMcpPromptHandler {
+    @inject(ClientId) protected clientId: string;
+    @inject(ModelState) protected modelState: ModelState;
+    @inject(McpIdAliasService) protected aliasService: McpIdAliasService;
+
+    /** Throw {@link McpToolError} for expected errors; the base wraps. */
+    protected abstract createResult(args: T): MaybePromise<McpPromptResult>;
+
+    /**
+     * Public dispatch entry point invoked by {@link McpServerLauncher}'s SDK callback.
+     */
+    handle(args: T): Promise<McpPromptResult> {
+        return this.execute(() => this.createResult(args));
+    }
+}
+
+/**
+ * Multi-binding identifier for diagram-scope prompt handler constructors. See
+ * {@link McpDiagramToolHandlerConstructor} for the lifecycle pattern — same shape, applied to
+ * prompt handlers.
+ */
+export type McpDiagramPromptHandlerConstructor = interfaces.Newable<AbstractMcpDiagramPromptHandler<any>>;
+export const McpDiagramPromptHandlerConstructor = Symbol('McpDiagramPromptHandlerConstructor');

package/src/server/mcp-request-context.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * 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 { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export type McpRequestExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+
+/**
+ * Module-level `AsyncLocalStorage` carrying the SDK's per-request `extra` (notification sender,
+ * progress token, request id, session id) for the duration of a tool/resource/prompt callback.
+ *
+ * The handler bases (tool / resource / prompt) wrap each registered SDK callback in
+ * `mcpRequestContext.run(extra, () => …)`. Anything inside the handler — and any await chain
+ * branching off it — can read the active context via {@link mcpRequestContext.getStore}.
+ *
+ * This lets {@link McpLogger} forward logs to the MCP client without every handler having to
+ * thread `extra` through its own signature, and lets future progress-emission code (P1f / PNG
+ * export) reach the same channel from inside `requestUntil` chains.
+ *
+ * Concurrent requests on the same MCP session each get their own AsyncLocalStorage frame —
+ * no cross-talk. Code that runs OUTSIDE a request (init contributions, background timers)
+ * sees `undefined` from `getStore()`.
+ */
+export const mcpRequestContext = new AsyncLocalStorage<McpRequestExtra>();