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

package/lib/server/mcp-handler-shared.d.ts

@@ -0,0 +1,142 @@
+/********************************************************************************
+ * 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 { ActionDispatcher, ClientSessionManager, RequestAction, ResponseAction } from '@eclipse-glsp/server';
+import { CallToolResult, GetPromptResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types';
+/**
+ * **Note on terminology** — "session" in this file always refers to a **GLSP client session**
+ * (one open diagram, tracked by core's `ClientSessionManager`). It is unrelated to the
+ * **MCP session** concept used in {@link mcp-session.ts} and {@link mcp-http-transport.ts}
+ * (one MCP client connection to the HTTP endpoint). The two have independent lifetimes — see
+ * the docstring at the top of `mcp-session.ts` for the full disambiguation.
+ *
+ * Diagram-scope handler bases ({@link AbstractMcpDiagramToolHandler} et al.) inject their per-session
+ * services directly per GLSP session. The launcher's dispatcher resolves the
+ * {@link McpDiagramScopedInput.sessionId} input field via `ClientSessionManager` to route a
+ * tool/resource/prompt call to the right per-session handler instance.
+ */
+/** Result returned from `tools/call`. Aliased so handler signatures read in GLSP terms. */
+export type McpToolResult = CallToolResult;
+/** Result returned from `resources/read`. Aliased so handler signatures read in GLSP terms. */
+export type McpResourceResult = ReadResourceResult;
+/** Result returned from `prompts/get`. Aliased so handler signatures read in GLSP terms. */
+export type McpPromptResult = GetPromptResult;
+/** One content part of a {@link McpToolResult}. Tool results are an array of these. */
+export type McpToolResultContent = CallToolResult['content'][number];
+/** One content part of a {@link McpResourceResult}. Resource reads are an array of these. */
+export type McpResourceResultContent = ReadResourceResult['contents'][number];
+/**
+ * Single-content body returned by a session-scope resource handler. The base wraps it with
+ * `uri` + the handler's declared `mimeType` to produce the SDK `ReadResourceResult`.
+ *
+ * `structured` is dual-emit overflow used only when the resource is exposed as a tool
+ * (`toolAlternativeInputSchema` set) AND the handler also declares `toolAlternativeOutputSchema`.
+ * The framework forwards it to `CallToolResult.structuredContent`. Resource-protocol reads ignore
+ * it — the spec has no equivalent slot on `ReadResourceResult`.
+ */
+export type McpResourceContent = ({
+    text: string;
+} | {
+    blob: string;
+}) & {
+    structured?: McpStructuredContent;
+};
+/** Structured payload for `CallToolResult.structuredContent`. The MCP spec requires an object. */
+export interface McpStructuredContent {
+    [key: string]: unknown;
+}
+/**
+ * Throw inside `createResult` to surface an expected, user-facing error to the MCP client.
+ * The base class catches it and emits an `isError: true` result. Unexpected errors
+ * (non-`McpToolError`) are logged and their extracted message is surfaced too.
+ *
+ * Use one of the named subclasses (`McpMissingParamError`, `McpSessionNotFoundError`,
+ * `McpReadOnlyError`, `McpElementsNotFoundError`, `McpRequestTimeoutError`) where they fit;
+ * otherwise throw `new McpToolError('context-specific message')`.
+ */
+export declare class McpToolError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Thrown when a required input parameter is missing or empty. */
+export declare class McpMissingParamError extends McpToolError {
+    readonly paramName: string;
+    constructor(paramName: string);
+}
+/** Thrown when no GLSP client session matches the provided id. */
+export declare class McpSessionNotFoundError extends McpToolError {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+/** Thrown when a write-style operation targets a read-only model. */
+export declare class McpReadOnlyError extends McpToolError {
+    constructor();
+}
+/** Thrown by handlers that look up elements by id and find some absent from the model. */
+export declare class McpElementsNotFoundError extends McpToolError {
+    readonly missingIds: readonly string[];
+    constructor(missingIds: readonly string[]);
+}
+/** Thrown when a request/response round-trip (`ActionDispatcher.requestUntil`) exceeds its timeout. */
+export declare class McpRequestTimeoutError extends McpToolError {
+    readonly operation: string;
+    readonly timeoutMs: number;
+    constructor(operation: string, timeoutMs: number);
+}
+/**
+ * Catch `McpToolError` thrown by pre-handler routing (e.g. `requireDiagramToolHandler`) and
+ * convert it to an `isError: true` tool result. Without this, those throws surface as
+ * JSON-RPC `-32603` instead of a self-correctable tool error.
+ */
+export declare function runWithToolErrorEnvelope(producer: () => Promise<CallToolResult>): Promise<CallToolResult>;
+/** Stable codes surfaced in `CallToolResult.structuredContent.code` so the LLM can self-correct on a known taxonomy. */
+export declare const McpToolErrorCodes: {
+    /** GLSP session disposed mid-call (server shutdown or session disposal). */
+    readonly SessionDisposed: "session-disposed";
+};
+export type McpToolErrorCode = (typeof McpToolErrorCodes)[keyof typeof McpToolErrorCodes];
+/** True when `err` is a GLSP-session-disposed rejection from the action dispatcher's dispose hooks. */
+export declare function isSessionDisposedError(err: unknown): boolean;
+/** Resolve a known `McpToolErrorCode` for an error, or `undefined` if it is generic. */
+export declare function errorCodeFor(err: unknown): McpToolErrorCode | undefined;
+/** Build an `isError: true` tool result, attaching `structuredContent: { code }` when known. */
+export declare function toolErrorResult(message: string, code?: McpToolErrorCode): CallToolResult;
+/** Returns a useful message for a value caught from a `throw`. */
+export declare function extractErrorMessage(error: unknown): string;
+/**
+ * Dispatch a request action and await its response, surfacing failures uniformly.
+ *
+ * The `ActionDispatcher.requestUntil` API today returns `undefined` on timeout (default
+ * `rejectOnTimeout: false`) and throws when the client emits a `RejectAction`. Handlers
+ * that consume it have to branch on both. This helper consolidates that branching:
+ *
+ * -   On client-side `RejectAction` → throws `McpToolError` with `${label} failed: <inner>`.
+ * -   On timeout (undefined return) → throws `McpRequestTimeoutError(label, timeoutMs)`.
+ * -   Otherwise → returns the typed response.
+ *
+ * Prefer the base-class methods (`OperationMcpDiagramToolHandler.requestAction` /
+ * `AbstractMcpDiagramResourceHandler.requestAction`) over calling this directly — they default
+ * the label to the handler's `name` field and pass `this.actionDispatcher`. This free
+ * function is the canonical implementation behind both.
+ */
+export declare function requestActionOrFail<R extends ResponseAction>(dispatcher: ActionDispatcher, request: RequestAction<R>, timeoutMs: number, label: string): Promise<R>;
+/**
+ * Pick a target session for server-scope handlers (e.g. prompts) where `sessionId` is optional.
+ * Resolution: explicit id (validated to exist) → single open session → throw with the available
+ * ids when ambiguous, throw when none open. Keeps user-invoked entry points like slash-command
+ * prompts ergonomic in the common single-diagram case while staying explicit when not.
+ */
+export declare function resolveActiveSessionId(clientSessionManager: ClientSessionManager, explicitSessionId: string | undefined): string;
+//# sourceMappingURL=mcp-handler-shared.d.ts.map

package/lib/server/mcp-handler-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-handler-shared.d.ts","sourceRoot":"","sources":["../../src/server/mcp-handler-shared.ts"],"names":[],"mappings":"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"}

package/lib/server/mcp-handler-shared.js

@@ -0,0 +1,199 @@
+"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.McpToolErrorCodes = exports.McpRequestTimeoutError = exports.McpElementsNotFoundError = exports.McpReadOnlyError = exports.McpSessionNotFoundError = exports.McpMissingParamError = exports.McpToolError = void 0;
+exports.runWithToolErrorEnvelope = runWithToolErrorEnvelope;
+exports.isSessionDisposedError = isSessionDisposedError;
+exports.errorCodeFor = errorCodeFor;
+exports.toolErrorResult = toolErrorResult;
+exports.extractErrorMessage = extractErrorMessage;
+exports.requestActionOrFail = requestActionOrFail;
+exports.resolveActiveSessionId = resolveActiveSessionId;
+// ─── Errors ──────────────────────────────────────────────────────────────────
+/**
+ * Throw inside `createResult` to surface an expected, user-facing error to the MCP client.
+ * The base class catches it and emits an `isError: true` result. Unexpected errors
+ * (non-`McpToolError`) are logged and their extracted message is surfaced too.
+ *
+ * Use one of the named subclasses (`McpMissingParamError`, `McpSessionNotFoundError`,
+ * `McpReadOnlyError`, `McpElementsNotFoundError`, `McpRequestTimeoutError`) where they fit;
+ * otherwise throw `new McpToolError('context-specific message')`.
+ */
+class McpToolError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'McpToolError';
+    }
+}
+exports.McpToolError = McpToolError;
+/** Thrown when a required input parameter is missing or empty. */
+class McpMissingParamError extends McpToolError {
+    constructor(paramName) {
+        super(`No '${paramName}' provided.`);
+        this.paramName = paramName;
+        this.name = 'McpMissingParamError';
+    }
+}
+exports.McpMissingParamError = McpMissingParamError;
+/** Thrown when no GLSP client session matches the provided id. */
+class McpSessionNotFoundError extends McpToolError {
+    constructor(sessionId) {
+        super(`Session not found: ${sessionId}`);
+        this.sessionId = sessionId;
+        this.name = 'McpSessionNotFoundError';
+    }
+}
+exports.McpSessionNotFoundError = McpSessionNotFoundError;
+/** Thrown when a write-style operation targets a read-only model. */
+class McpReadOnlyError extends McpToolError {
+    constructor() {
+        super('Model is read-only.');
+        this.name = 'McpReadOnlyError';
+    }
+}
+exports.McpReadOnlyError = McpReadOnlyError;
+/** Thrown by handlers that look up elements by id and find some absent from the model. */
+class McpElementsNotFoundError extends McpToolError {
+    constructor(missingIds) {
+        super(`Element(s) not found: ${missingIds.join(', ')}`);
+        this.missingIds = missingIds;
+        this.name = 'McpElementsNotFoundError';
+    }
+}
+exports.McpElementsNotFoundError = McpElementsNotFoundError;
+/** Thrown when a request/response round-trip (`ActionDispatcher.requestUntil`) exceeds its timeout. */
+class McpRequestTimeoutError extends McpToolError {
+    constructor(operation, timeoutMs) {
+        super(`${operation} timed out after ${timeoutMs}ms.`);
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+        this.name = 'McpRequestTimeoutError';
+    }
+}
+exports.McpRequestTimeoutError = McpRequestTimeoutError;
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Catch `McpToolError` thrown by pre-handler routing (e.g. `requireDiagramToolHandler`) and
+ * convert it to an `isError: true` tool result. Without this, those throws surface as
+ * JSON-RPC `-32603` instead of a self-correctable tool error.
+ */
+async function runWithToolErrorEnvelope(producer) {
+    try {
+        return await producer();
+    }
+    catch (err) {
+        if (err instanceof McpToolError) {
+            return toolErrorResult(err.message, errorCodeFor(err));
+        }
+        throw err;
+    }
+}
+/** Stable codes surfaced in `CallToolResult.structuredContent.code` so the LLM can self-correct on a known taxonomy. */
+exports.McpToolErrorCodes = {
+    /** GLSP session disposed mid-call (server shutdown or session disposal). */
+    SessionDisposed: 'session-disposed'
+};
+/** True when `err` is a GLSP-session-disposed rejection from the action dispatcher's dispose hooks. */
+function isSessionDisposedError(err) {
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    return /ActionDispatcher disposed|cancelled: dispatcher disposed/.test(err.message);
+}
+/** Resolve a known `McpToolErrorCode` for an error, or `undefined` if it is generic. */
+function errorCodeFor(err) {
+    if (isSessionDisposedError(err)) {
+        return exports.McpToolErrorCodes.SessionDisposed;
+    }
+    return undefined;
+}
+/** Build an `isError: true` tool result, attaching `structuredContent: { code }` when known. */
+function toolErrorResult(message, code) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: message }],
+        ...(code ? { structuredContent: { code } } : {})
+    };
+}
+/** Returns a useful message for a value caught from a `throw`. */
+function extractErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return String(error);
+}
+/**
+ * Dispatch a request action and await its response, surfacing failures uniformly.
+ *
+ * The `ActionDispatcher.requestUntil` API today returns `undefined` on timeout (default
+ * `rejectOnTimeout: false`) and throws when the client emits a `RejectAction`. Handlers
+ * that consume it have to branch on both. This helper consolidates that branching:
+ *
+ * -   On client-side `RejectAction` → throws `McpToolError` with `${label} failed: <inner>`.
+ * -   On timeout (undefined return) → throws `McpRequestTimeoutError(label, timeoutMs)`.
+ * -   Otherwise → returns the typed response.
+ *
+ * Prefer the base-class methods (`OperationMcpDiagramToolHandler.requestAction` /
+ * `AbstractMcpDiagramResourceHandler.requestAction`) over calling this directly — they default
+ * the label to the handler's `name` field and pass `this.actionDispatcher`. This free
+ * function is the canonical implementation behind both.
+ */
+async function requestActionOrFail(dispatcher, request, timeoutMs, label) {
+    let response;
+    try {
+        response = await dispatcher.requestUntil(request, timeoutMs);
+    }
+    catch (err) {
+        // Preserve the original rejection error as `cause` so adopters whose `RejectAction`
+        // sets `detail` (which core flattens into the message via `${message}: ${detail}`) can
+        // still inspect the underlying object — both for diagnostic logging and for an LLM
+        // surface that wants to disambiguate transient vs. permanent failures.
+        throw new McpToolError(`${label} failed: ${extractErrorMessage(err)}`, err);
+    }
+    if (!response) {
+        throw new McpRequestTimeoutError(label, timeoutMs);
+    }
+    return response;
+}
+/**
+ * Pick a target session for server-scope handlers (e.g. prompts) where `sessionId` is optional.
+ * Resolution: explicit id (validated to exist) → single open session → throw with the available
+ * ids when ambiguous, throw when none open. Keeps user-invoked entry points like slash-command
+ * prompts ergonomic in the common single-diagram case while staying explicit when not.
+ */
+function resolveActiveSessionId(clientSessionManager, explicitSessionId) {
+    const sessions = clientSessionManager.getSessions();
+    if (explicitSessionId) {
+        if (!sessions.some(session => session.id === explicitSessionId)) {
+            throw new McpToolError(`Unknown sessionId: ${explicitSessionId}`);
+        }
+        return explicitSessionId;
+    }
+    if (sessions.length === 0) {
+        throw new McpToolError('No open diagram sessions to target.');
+    }
+    if (sessions.length === 1) {
+        return sessions[0].id;
+    }
+    const ids = sessions.map(session => `'${session.id}'`).join(', ');
+    throw new McpToolError(`Multiple sessions open (${ids}); pass \`sessionId\` to disambiguate.`);
+}
+//# sourceMappingURL=mcp-handler-shared.js.map

package/lib/server/mcp-handler-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-handler-shared.js","sourceRoot":"","sources":["../../src/server/mcp-handler-shared.ts"],"names":[],"mappings":"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"}

package/lib/server/mcp-http-transport.d.ts

@@ -0,0 +1,93 @@
+/********************************************************************************
+ * 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 { Deferred, Disposable, Emitter, Logger } from '@eclipse-glsp/server';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { Express } from 'express';
+import * as express from 'express';
+import * as http from 'http';
+import { AddressInfo } from 'net';
+import { McpServerOptions } from './mcp-options';
+import type { FullMcpServerConfiguration } from './mcp-server-launcher';
+import { McpSession } from './mcp-session';
+/**
+ * Where this transport can be reached. Network transports populate `url`;
+ * future in-process or stdio transports would leave it undefined.
+ */
+export interface TransportEndpoint {
+    url?: string;
+    headers?: Record<string, string>;
+}
+export declare class McpHttpTransport implements Disposable {
+    protected logger: Logger;
+    protected _app?: Express;
+    protected _server?: http.Server;
+    protected _addressInfo: Deferred<AddressInfo>;
+    protected sessions: Map<string, StreamableHTTPServerTransport>;
+    protected onSessionInitializedEmitter: Emitter<McpSession>;
+    onSessionInitialized: import("@eclipse-glsp/server").Event<McpSession>;
+    protected onSessionClosedEmitter: Emitter<string>;
+    onSessionClosed: import("@eclipse-glsp/server").Event<string>;
+    protected serverOptions: McpServerOptions;
+    constructor(logger: Logger);
+    get app(): Express | undefined;
+    get server(): http.Server | undefined;
+    getAddress(): Promise<AddressInfo>;
+    start(config: FullMcpServerConfiguration): Promise<TransportEndpoint>;
+    /**
+     * Translate a pre-listen failure into an actionable error and reject the address-info
+     * deferred so `start()` propagates it to the caller. `EADDRINUSE` gets a tailored hint
+     * about overriding via `mcpServer.port`; other codes pass through unchanged.
+     */
+    protected handleListenError(err: NodeJS.ErrnoException, host: string, port: number): void;
+    /**
+     * Hook for subclasses to register middleware on the Express app before the MCP routes
+     * are mounted. Called once during {@link start}, after the app is created and before
+     * `POST` / `GET` / `DELETE` handlers are added.
+     *
+     * Default behavior: install an Origin allowlist if one is configured. Host-header
+     * validation is already wired by the SDK's `createMcpExpressApp` (using the same
+     * `allowedHosts` we forward in {@link start}); we don't duplicate it here. Subclasses
+     * that override SHOULD `super.configureExpressApp(app)` to keep the origin gate in place;
+     * pre-existing security middleware can run before or after by calling super at the
+     * appropriate point.
+     */
+    protected configureExpressApp(app: Express): void;
+    /**
+     * Validate the `MCP-Protocol-Version` header per the Streamable HTTP transport spec.
+     * Initialize POSTs negotiate the version in the body — the header isn't expected there.
+     * For every other request: absent header → pass through (the spec mandates the server
+     * default to `2025-03-26`); present-but-unsupported → respond `400` with a JSON-RPC error
+     * envelope so the client knows which versions to retry with.
+     */
+    protected validateProtocolVersionHeader(req: express.Request, res: express.Response, next: express.NextFunction): void;
+    protected toServerUrl({ address, family, port }: AddressInfo, route: string, protocol?: string): string;
+    protected listening(): void;
+    protected handlePostRequest(req: express.Request, res: express.Response): Promise<void>;
+    /**
+     * Handle GET requests for SSE streams (using built-in support from StreamableHTTP)
+     */
+    protected handleGetRequest(req: express.Request, res: express.Response): Promise<void>;
+    /**
+     * Handle DELETE requests for session termination (according to MCP spec).
+     */
+    protected handleDeleteRequest(req: express.Request, res: express.Response): Promise<void>;
+    protected getOrCreateClient(req: express.Request, res: express.Response): StreamableHTTPServerTransport | undefined;
+    protected getClient(req: express.Request, res: express.Response): StreamableHTTPServerTransport | undefined;
+    protected createClient(): StreamableHTTPServerTransport;
+    protected closeClient(sessionId?: string): void;
+    dispose(): void;
+}
+//# sourceMappingURL=mcp-http-transport.d.ts.map

package/lib/server/mcp-http-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-http-transport.d.ts","sourceRoot":"","sources":["../../src/server/mcp-http-transport.ts"],"names":[],"mappings":"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"}