|
| 1 | +# Workflow Server MCP Demo (browser) |
| 2 | + |
| 3 | +A browser demo for the `@eclipse-glsp/server-mcp` portable Fetch handler. The page opens a |
| 4 | +workflow GLSP session inside an in-page Web Worker and drives the MCP server through a |
| 5 | +Service Worker that intercepts `fetch('/mcp', …)` and proxies the request to the Worker via |
| 6 | +`MessageChannel`. |
| 7 | + |
| 8 | +This package is **private** — it ships nothing; it's a local demo and manual test bench for |
| 9 | +the portable handler. |
| 10 | + |
| 11 | +## Why only a browser demo? |
| 12 | + |
| 13 | +The browser variant needs a custom harness because **external MCP clients can't reach an |
| 14 | +in-page launcher**: a browser tab doesn't accept inbound network traffic. The Service Worker |
| 15 | +in this demo is what makes the in-page launcher reachable to a same-origin MCP client. |
| 16 | + |
| 17 | +For the **Node variant**, no demo is needed in this repo — the launcher binds a real HTTP |
| 18 | +listener and announces its URL via stdout (`[GLSP-MCP-Server]:Ready. {…}`). Point any MCP |
| 19 | +client at that URL: |
| 20 | + |
| 21 | +- The official **[MCP Inspector](https://github.com/modelcontextprotocol/inspector)** is the |
| 22 | + best manual debug tool — runs as a local web UI and lets you exercise tools, prompts and |
| 23 | + resources interactively. |
| 24 | +- **Claude Code**, **Cursor**, or any other MCP-aware client also work. |
| 25 | + |
| 26 | +The Node path is additionally covered by the automated end-to-end spec at |
| 27 | +`packages/server-mcp/src/node/server/mcp-http-transport-e2e.spec.ts`, which runs an MCP SDK |
| 28 | +`Client` over real HTTP against the launcher. |
| 29 | + |
| 30 | +## Running |
| 31 | + |
| 32 | +From the repository root: |
| 33 | + |
| 34 | +```bash |
| 35 | +yarn start:mcp-demo |
| 36 | +``` |
| 37 | + |
| 38 | +This builds the workflow server, copies the worker bundle from |
| 39 | +`@eclipse-glsp-examples/workflow-server-bundled-web`, builds the page-side bundle, and serves |
| 40 | +the directory on `http://localhost:8000/`. |
| 41 | + |
| 42 | +Open `http://localhost:8000/` in any modern browser. Step through the buttons |
| 43 | +top-to-bottom; the workflow auto-renders once MCP is initialized, and **Create task** |
| 44 | +mutates the live session. |
| 45 | + |
| 46 | +## What it exercises |
| 47 | + |
| 48 | +1. The page acts as a minimal GLSP JSON-RPC client over `postMessage` to the in-page Web |
| 49 | + Worker (using `vscode-jsonrpc/browser`, bundled). |
| 50 | +2. GLSP `initialize` carries `mcpServer: {}` — the Worker's per-connection child container |
| 51 | + activates `BrowserMcpServerModule`'s launcher as a `GLSPServerInitializer`. |
| 52 | +3. `initializeClientSession` opens a real workflow GLSP session with |
| 53 | + `diagramType: workflow-diagram`. |
| 54 | +4. A Service Worker (`mcp-service-worker.js`) intercepts `fetch('/mcp', …)` and proxies the |
| 55 | + request through a `MessageChannel` to the Worker. |
| 56 | +5. MCP tools (`initialize`, `tools/list`, `session-info`, `query-elements`, `diagram-model`, |
| 57 | + `create-nodes`) round-trip end-to-end against the live session. |
| 58 | + |
| 59 | +The on-page SVG is a minimal schematic renderer — **not** the GLSP client; its only purpose |
| 60 | +is to make the MCP handlers' output visible so the demo can be eyeballed end-to-end. |
| 61 | + |
| 62 | +## Hard reset |
| 63 | + |
| 64 | +If a stale Service Worker is misbehaving: DevTools → Application → Service Workers → |
| 65 | +Unregister, then close the tab and re-open. The page's Worker bundle URL is cache-busted per |
| 66 | +load, but the SW itself updates only on full lifecycle restart. |
0 commit comments