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

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

@@ -0,0 +1,247 @@
+/********************************************************************************
+ * 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.
+ */
+
+// ─── MCP-protocol type aliases (Mcp prefix on GLSP-side) ─────────────────────
+
+/** 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;
+}
+
+// ─── 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')`.
+ */
+export class McpToolError extends Error {
+    constructor(
+        message: string,
+        readonly cause?: unknown
+    ) {
+        super(message);
+        this.name = 'McpToolError';
+    }
+}
+
+/** Thrown when a required input parameter is missing or empty. */
+export class McpMissingParamError extends McpToolError {
+    constructor(readonly paramName: string) {
+        super(`No '${paramName}' provided.`);
+        this.name = 'McpMissingParamError';
+    }
+}
+
+/** Thrown when no GLSP client session matches the provided id. */
+export class McpSessionNotFoundError extends McpToolError {
+    constructor(readonly sessionId: string) {
+        super(`Session not found: ${sessionId}`);
+        this.name = 'McpSessionNotFoundError';
+    }
+}
+
+/** Thrown when a write-style operation targets a read-only model. */
+export class McpReadOnlyError extends McpToolError {
+    constructor() {
+        super('Model is read-only.');
+        this.name = 'McpReadOnlyError';
+    }
+}
+
+/** Thrown by handlers that look up elements by id and find some absent from the model. */
+export class McpElementsNotFoundError extends McpToolError {
+    constructor(readonly missingIds: readonly string[]) {
+        super(`Element(s) not found: ${missingIds.join(', ')}`);
+        this.name = 'McpElementsNotFoundError';
+    }
+}
+
+/** Thrown when a request/response round-trip (`ActionDispatcher.requestUntil`) exceeds its timeout. */
+export class McpRequestTimeoutError extends McpToolError {
+    constructor(
+        readonly operation: string,
+        readonly timeoutMs: number
+    ) {
+        super(`${operation} timed out after ${timeoutMs}ms.`);
+        this.name = '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.
+ */
+export async function runWithToolErrorEnvelope(producer: () => Promise<CallToolResult>): Promise<CallToolResult> {
+    try {
+        return await producer();
+    } catch (err: unknown) {
+        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. */
+export const McpToolErrorCodes = {
+    /** GLSP session disposed mid-call (server shutdown or session disposal). */
+    SessionDisposed: 'session-disposed'
+} as const;
+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 function isSessionDisposedError(err: unknown): boolean {
+    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. */
+export function errorCodeFor(err: unknown): McpToolErrorCode | undefined {
+    if (isSessionDisposedError(err)) {
+        return McpToolErrorCodes.SessionDisposed;
+    }
+    return undefined;
+}
+
+/** Build an `isError: true` tool result, attaching `structuredContent: { code }` when known. */
+export function toolErrorResult(message: string, code?: McpToolErrorCode): CallToolResult {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: message }],
+        ...(code ? { structuredContent: { code } } : {})
+    };
+}
+
+/** Returns a useful message for a value caught from a `throw`. */
+export function extractErrorMessage(error: unknown): string {
+    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.
+ */
+export async function requestActionOrFail<R extends ResponseAction>(
+    dispatcher: ActionDispatcher,
+    request: RequestAction<R>,
+    timeoutMs: number,
+    label: string
+): Promise<R> {
+    let response: R | undefined;
+    try {
+        response = await dispatcher.requestUntil<R>(request, timeoutMs);
+    } catch (err: unknown) {
+        // 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.
+ */
+export function resolveActiveSessionId(clientSessionManager: ClientSessionManager, explicitSessionId: string | undefined): string {
+    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.`);
+}

package/src/server/mcp-http-transport-e2e.spec.ts

@@ -0,0 +1,151 @@
+/********************************************************************************
+ * 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 { Logger, NullLogger } from '@eclipse-glsp/server';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { expect } from 'chai';
+import { Container, ContainerModule } from 'inversify';
+import * as z from 'zod/v4';
+import { McpHttpTransport } from './mcp-http-transport';
+import { McpServerOptions } from './mcp-options';
+import { rawHttpRequest } from './raw-http.spec';
+
+function buildTransport(): McpHttpTransport {
+    const container = new Container();
+    container.load(
+        new ContainerModule(bind => {
+            bind(Logger).toConstantValue(new NullLogger());
+            const opts = new McpServerOptions();
+            opts.values = {};
+            bind(McpServerOptions).toConstantValue(opts);
+            bind(McpHttpTransport).toSelf().inSingletonScope();
+        })
+    );
+    return container.get<McpHttpTransport>(McpHttpTransport);
+}
+
+/**
+ * WN-058 — End-to-end smoke test that boots {@link McpHttpTransport},
+ * connects a real SDK MCP client over Streamable HTTP, and exercises a tool
+ * round-trip (`echo`). Validates that the transport implements the protocol
+ * conformantly without depending on the GLSP handler stack.
+ */
+describe('McpHttpTransport (WN-058 e2e — real MCP SDK client over HTTP)', () => {
+    let httpServer: McpHttpTransport | undefined;
+    let client: Client | undefined;
+
+    /**
+     * Idempotent client close: a test that already tore the SDK client down (e.g. after a
+     * spec-mandated DELETE on the same session) leaves the local `client` ref pointing at a
+     * closed instance. `Client.close()` is safe to call twice on the SDK side, but we still
+     * swallow any throw so afterEach is robust under partial-progress failures too.
+     */
+    async function safeClose(target: Client | undefined): Promise<void> {
+        if (!target) return;
+        try {
+            await target.close();
+        } catch {
+            /* ignore — best effort */
+        }
+    }
+
+    afterEach(async () => {
+        await safeClose(client);
+        client = undefined;
+        httpServer?.dispose();
+        httpServer = undefined;
+    });
+
+    it('round-trips tools/list and tools/call against a registered echo tool', async () => {
+        httpServer = buildTransport();
+
+        // Wire one fresh `McpServer` per accepted session, register an `echo` tool,
+        // and let the server attach to the transport. Mirrors what `McpServerLauncher`
+        // does; kept inline here so the test exercises only the transport path.
+        httpServer.onSessionInitialized(session => {
+            const mcpServer = new McpServer({ name: 'glsp-test', version: '1.0.0' }, { capabilities: {} });
+            mcpServer.registerTool(
+                'echo',
+                { description: 'Returns the supplied message verbatim.', inputSchema: { message: z.string() } },
+                async ({ message }) => ({ content: [{ type: 'text', text: message }] })
+            );
+            mcpServer.connect(session);
+        });
+
+        const endpoint = await httpServer.start({
+            port: 0,
+            host: '127.0.0.1',
+            route: '/mcp',
+            name: 'glsp-test',
+            options: { dataMode: 'tools' }
+        });
+        expect(endpoint.url, 'transport must report a URL after start()').to.be.a('string');
+
+        client = new Client({ name: 'wn-058-test-client', version: '1.0.0' });
+        await client.connect(new StreamableHTTPClientTransport(new URL(endpoint.url!)));
+
+        const tools = await client.listTools();
+        expect(tools.tools.map(tool => tool.name)).to.include('echo');
+
+        const result = await client.callTool({ name: 'echo', arguments: { message: 'hello GLSP' } });
+        expect(result.isError).to.not.equal(true);
+        expect(result.content).to.have.lengthOf(1);
+        const [block] = result.content as Array<{ type: string; text?: string }>;
+        expect(block.type).to.equal('text');
+        expect(block.text).to.equal('hello GLSP');
+    });
+
+    it('DELETE /mcp terminates the session; subsequent POSTs with the same id return 404 (§ #5)', async () => {
+        httpServer = buildTransport();
+        httpServer.onSessionInitialized(session => {
+            const mcpServer = new McpServer({ name: 'glsp-test', version: '1.0.0' }, { capabilities: {} });
+            mcpServer.connect(session);
+        });
+        const endpoint = await httpServer.start({
+            port: 0,
+            host: '127.0.0.1',
+            route: '/mcp',
+            name: 'glsp-test',
+            options: { dataMode: 'tools' }
+        });
+
+        client = new Client({ name: 'delete-smoke-test', version: '1.0.0' });
+        const clientTransport = new StreamableHTTPClientTransport(new URL(endpoint.url!));
+        await client.connect(clientTransport);
+        const sessionId = clientTransport.sessionId;
+        expect(sessionId, 'SDK transport should expose the minted session id after initialize').to.be.a('string');
+
+        const { port } = await httpServer.getAddress();
+
+        // 1. Spec § Session Management #5 — DELETE terminates the session.
+        const deleteRes = await rawHttpRequest(port, 'DELETE', { 'mcp-session-id': sessionId! });
+        expect(deleteRes.status, 'DELETE should succeed for an active session').to.be.lessThan(300);
+
+        // 2. After termination, the same id MUST be rejected with 404 (§ #3) — proves the
+        //    session was actually removed, not just acked.
+        const followUp = await rawHttpRequest(
+            port,
+            'POST',
+            { 'mcp-session-id': sessionId! },
+            { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }
+        );
+        expect(followUp.status).to.equal(404);
+        const payload = JSON.parse(followUp.body);
+        expect(payload.error.code).to.equal(-32001);
+    });
+});