feat: add MCP client-agnostic transport and discovery

- Add stdio and Streamable HTTP MCP transports with per-session isolation
- Add config normalization and tool-name adapter for server-prefixed names
- Add compact discovery mode (MCP_PERFORMANCE_MODE) reducing payload by 42%
- Add smoke tests for AdaL, Claude, Cursor, OpenAI Agents SDK
- Add client-specific configuration examples and migration notes
- Keep default stdio flow intact for existing AdaL users

Author: chindris-mihai-alexandru

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Node ${{ matrix.node }} / ${{ matrix.transport }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [20, 22]
+        transport: [stdio, http]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      - run: npm ci
+
+      - run: npm run type-check
+
+      - run: npm run build
+
+      - run: npm test -- --run
+
+      - name: MCP smoke
+        env:
+          MCP_TRANSPORT: ${{ matrix.transport }}
+          RUN_MCP_SMOKE: 'true'
+        run: |
+          if [ "${{ matrix.transport }}" = "stdio" ]; then
+            npm run test:smoke:stdio
+          else
+            npm run test:smoke:http
+          fi
+
+      - name: Tool discovery payload budget
+        run: npm run bench:tools

scripts/bench-tool-definitions.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import { listToolsForConfig } from '../dist/index.js'
+
+const baseConfig = {
+  serverName: 'tldraw',
+  serverVersion: '0.2.0',
+  expressServerUrl: 'http://127.0.0.1:3000',
+  transport: 'stdio',
+  httpHost: '127.0.0.1',
+  httpPort: 3333,
+  httpPath: '/mcp',
+  allowedOrigins: ['http://127.0.0.1', 'http://localhost'],
+  allowedHosts: ['127.0.0.1', 'localhost'],
+  client: 'generic',
+  includeServerInToolNames: false,
+}
+
+const fullTools = listToolsForConfig({ ...baseConfig, performanceMode: false })
+const compactTools = listToolsForConfig({ ...baseConfig, performanceMode: true })
+
+const fullBytes = Buffer.byteLength(JSON.stringify(fullTools), 'utf8')
+const compactBytes = Buffer.byteLength(JSON.stringify(compactTools), 'utf8')
+const reduction = 1 - compactBytes / fullBytes
+
+const result = {
+  fullBytes,
+  compactBytes,
+  reductionPercent: Number((reduction * 100).toFixed(2)),
+}
+
+console.log(JSON.stringify(result, null, 2))
+
+if (reduction < 0.30) {
+  console.error(`Expected MCP_PERFORMANCE_MODE to reduce discovery payload by at least 30%, got ${result.reductionPercent}%`)
+  process.exit(1)
+}

src/client-adapter.ts

@@ -0,0 +1,30 @@
+import type { TldrawMcpConfig } from './config.js'
+
+export interface ToolNameAdapter {
+  exposeName(name: string): string
+  normalizeName(name: string): string
+}
+
+export function createToolNameAdapter(config: TldrawMcpConfig): ToolNameAdapter {
+  const doubleUnderscorePrefix = `${config.serverName}__`
+  const singleUnderscorePrefix = `${config.serverName}_`
+
+  return {
+    exposeName(name: string): string {
+      return config.includeServerInToolNames ? `${doubleUnderscorePrefix}${name}` : name
+    },
+
+    normalizeName(name: string): string {
+      if (name.startsWith(doubleUnderscorePrefix)) {
+        return name.slice(doubleUnderscorePrefix.length)
+      }
+
+      // Some gateways/clients prefer single-underscore server prefixes.
+      if (name.startsWith(singleUnderscorePrefix)) {
+        return name.slice(singleUnderscorePrefix.length)
+      }
+
+      return name
+    },
+  }
+}

src/config.ts

@@ -0,0 +1,76 @@
+import 'dotenv/config'
+
+export type McpTransportKind = 'stdio' | 'http'
+export type McpClientKind = 'adal' | 'claude' | 'cursor' | 'openai' | 'generic'
+
+export interface TldrawMcpConfig {
+  serverName: string
+  serverVersion: string
+  expressServerUrl: string
+  transport: McpTransportKind
+  httpHost: string
+  httpPort: number
+  httpPath: string
+  allowedOrigins: string[]
+  allowedHosts: string[]
+  authToken?: string
+  client: McpClientKind
+  includeServerInToolNames: boolean
+  performanceMode: boolean
+}
+
+function readBool(name: string, fallback = false): boolean {
+  const value = process.env[name]
+  if (value === undefined) return fallback
+  return ['1', 'true', 'yes', 'on'].includes(value.toLowerCase())
+}
+
+function readList(name: string, fallback: string[]): string[] {
+  const value = process.env[name]
+  if (!value) return fallback
+  return value
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean)
+}
+
+function readClient(): McpClientKind {
+  const value = (process.env.MCP_CLIENT ?? 'generic').toLowerCase()
+  if (value === 'adal' || value === 'claude' || value === 'cursor' || value === 'openai') {
+    return value
+  }
+  return 'generic'
+}
+
+export function loadConfig(): TldrawMcpConfig {
+  const httpHost = process.env.MCP_HTTP_HOST ?? '127.0.0.1'
+  const httpPort = Number(process.env.MCP_HTTP_PORT ?? 3333)
+
+  return {
+    serverName: process.env.MCP_SERVER_NAME ?? 'tldraw',
+    serverVersion: process.env.MCP_SERVER_VERSION ?? '0.2.0',
+    expressServerUrl: process.env.EXPRESS_SERVER_URL ?? 'http://127.0.0.1:3000',
+    transport: process.env.MCP_TRANSPORT === 'http' ? 'http' : 'stdio',
+    httpHost,
+    httpPort,
+    httpPath: process.env.MCP_HTTP_PATH ?? '/mcp',
+    allowedOrigins: readList('MCP_ALLOWED_ORIGINS', [
+      'http://127.0.0.1',
+      'http://localhost',
+      'http://127.0.0.1:3000',
+      'http://localhost:3000',
+    ]),
+    allowedHosts: readList('MCP_ALLOWED_HOSTS', [
+      httpHost,
+      `${httpHost}:${httpPort}`,
+      '127.0.0.1',
+      `127.0.0.1:${httpPort}`,
+      'localhost',
+      `localhost:${httpPort}`,
+    ]),
+    authToken: process.env.MCP_AUTH_TOKEN,
+    client: readClient(),
+    includeServerInToolNames: readBool('INCLUDE_SERVER_IN_TOOL_NAMES', false),
+    performanceMode: readBool('MCP_PERFORMANCE_MODE', false),
+  }
+}

src/transport.ts

@@ -0,0 +1,96 @@
+import { randomUUID } from 'node:crypto'
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import type { Request, Response, NextFunction } from 'express'
+import type { TldrawMcpConfig } from './config.js'
+
+export type McpServerFactory = () => Server
+
+function isAllowedOrigin(config: TldrawMcpConfig, origin?: string): boolean {
+  if (!origin) return true
+  return config.allowedOrigins.some((allowed) => origin === allowed || origin.startsWith(`${allowed}:`))
+}
+
+function isAuthorized(config: TldrawMcpConfig, authorization?: string): boolean {
+  if (!config.authToken) return true
+  return authorization === `Bearer ${config.authToken}`
+}
+
+function securityMiddleware(config: TldrawMcpConfig) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    if (!isAllowedOrigin(config, req.header('origin') ?? undefined)) {
+      res.status(403).json({ error: 'Origin not allowed' })
+      return
+    }
+
+    if (!isAuthorized(config, req.header('authorization') ?? undefined)) {
+      res.status(401).json({ error: 'Unauthorized' })
+      return
+    }
+
+    next()
+  }
+}
+
+function isInitializeRequest(body: unknown): boolean {
+  if (!body || Array.isArray(body) || typeof body !== 'object') return false
+  return (body as { method?: unknown }).method === 'initialize'
+}
+
+export async function startMcpServer(createServer: McpServerFactory, config: TldrawMcpConfig): Promise<void> {
+  if (config.transport === 'stdio') {
+    await createServer().connect(new StdioServerTransport())
+    return
+  }
+
+  const app = createMcpExpressApp({
+    host: config.httpHost,
+    allowedHosts: config.allowedHosts,
+  })
+
+  app.use(securityMiddleware(config))
+
+  const transports = new Map<string, StreamableHTTPServerTransport>()
+
+  app.all(config.httpPath, async (req, res) => {
+    const requestedSessionId = req.header('mcp-session-id')
+    let transport = requestedSessionId ? transports.get(requestedSessionId) : undefined
+
+    if (!transport) {
+      if (!isInitializeRequest(req.body)) {
+        res.status(requestedSessionId ? 404 : 400).json({
+          error: requestedSessionId ? 'Unknown MCP session' : 'Missing MCP session; initialize first',
+        })
+        return
+      }
+
+      transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        enableJsonResponse: true,
+        allowedHosts: config.allowedHosts,
+        allowedOrigins: config.allowedOrigins,
+        enableDnsRebindingProtection: true,
+        onsessioninitialized: (sessionId) => {
+          transports.set(sessionId, transport!)
+        },
+        onsessionclosed: (sessionId) => {
+          transports.delete(sessionId)
+        },
+      })
+
+      transport.onclose = () => {
+        if (transport?.sessionId) transports.delete(transport.sessionId)
+      }
+
+      await createServer().connect(transport)
+    }
+
+    await transport.handleRequest(req, res, req.body)
+  })
+
+  await new Promise<void>((resolve) => {
+    app.listen(config.httpPort, config.httpHost, () => resolve())
+  })
+}