chore: update MCP configuration to use new ephemeral port for log ingestion, enhance error handling for MCP-Protocol-Version and session ID, and improve discovery file management

Author: regenrek

.browser-echo-mcp.json

@@ -1 +1 @@
-{"url":"http://127.0.0.1:5179","routeLogs":"/__client-logs","timestamp":1755812597005,"pid":42067}
+{"url":"http://127.0.0.1:57918","routeLogs":"/__client-logs","timestamp":1755854608470,"pid":49241}

.cursor/mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "browser-echo": {
       "command": "npx",
-      "args": ["https://pkg.pr.new/instructa/browser-echo/@browser-echo/mcp@f3039cc"]
+      "args": ["https://pkg.pr.new/instructa/browser-echo/@browser-echo/mcp@7123834"]
     }
   }
 }

packages/mcp/README.md

@@ -288,8 +288,9 @@ Best for local development with AI assistants:
 
 In stdio mode:
 - MCP communication happens over **stdio** (no HTTP MCP endpoint)
-- An **HTTP ingest server** runs at `http://127.0.0.1:5179/__client-logs` for browsers to POST logs
-- Console output: `MCP (stdio) listening on stdio (ingest HTTP active)`
+- An **HTTP ingest server** runs on an ephemeral port (127.0.0.1) for browsers to POST logs
+- The actual URL is written to `.browser-echo-mcp.json` in your project root and OS tmpdir
+- Console output (stderr): `MCP (stdio) listening on stdio (ingest HTTP active)`
 
 ### HTTP Mode
 
@@ -308,15 +309,14 @@ For web-based AI tools or when you need HTTP MCP access:
 ```
 
 In HTTP mode:
-- Full **Streamable HTTP** MCP endpoint at `http://127.0.0.1:5179/mcp`
-- HTTP ingest endpoint at `http://127.0.0.1:5179/__client-logs`
-- Console output: `MCP (Streamable HTTP) listening → http://127.0.0.1:5179/mcp`
+- Full **Streamable HTTP** MCP endpoint and HTTP ingest endpoint run on the specified host/port
+- Console output: `MCP (Streamable HTTP) listening → http://127.0.0.1:<port>/mcp`
 
 ### Custom Configuration
 
 ```bash
-# Custom ingest port in stdio mode
-node packages/mcp/bin/cli.mjs --port 8081
+# Custom ingest port in stdio mode (override ephemeral)
+BROWSER_ECHO_INGEST_PORT=8081 node packages/mcp/bin/cli.mjs
 
 # Custom HTTP server  
 node packages/mcp/bin/cli.mjs --http --host 0.0.0.0 --port 5179
@@ -397,7 +397,8 @@ publishLogEntry({
 ## Environment Variables
 
 - `BROWSER_ECHO_BUFFER_SIZE` — Max entries in memory (default: `1000`)
-- `BROWSER_ECHO_MCP_URL` — MCP server URL for framework forwarding (e.g., `http://127.0.0.1:5179/mcp`)
+- `BROWSER_ECHO_MCP_URL` — MCP server URL for framework forwarding (if set, frameworks bypass discovery)
+- `BROWSER_ECHO_INGEST_PORT` — Force a fixed ingest port in stdio mode (default: ephemeral)
 
 ---
 

packages/mcp/src/server.ts

@@ -61,12 +61,15 @@ export async function startServer(
 
     // Always bring up an ingest-only HTTP endpoint so clients/frameworks can POST logs
     const host = options.host || '127.0.0.1';
-    const port = (options.port ?? 5179) | 0;
+    // Use env override if provided, otherwise let OS pick an ephemeral port
+    const envIngest = process.env.BROWSER_ECHO_INGEST_PORT;
+    const requested = Number(envIngest || 0) | 0;
+    const port = requested > 0 ? requested : 0;
     const logsRoute = options.logsRoute || '/__client-logs';
     await startIngestOnlyServer(store, { host, port, logsRoute });
 
     // eslint-disable-next-line no-console
-    console.log('MCP (stdio) listening on stdio (ingest HTTP active)');
+    console.error('MCP (stdio) listening on stdio (ingest HTTP active)');
     return;
   }
 
@@ -152,19 +155,36 @@ export async function startHttpServer(
 
       // Normalize body for POST
       let bodyBuf: Buffer | undefined;
+      let isInitialize = false;
       if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
         const raw = await readRawBody(event);
         if (raw && typeof raw === 'string') bodyBuf = Buffer.from(raw);
         else if (raw && (raw as any) instanceof Uint8Array) bodyBuf = Buffer.from(raw as any);
 
-        // Allow tool calls without explicit session id by assigning a default
+        // Validate MCP-Protocol-Version if provided (allow missing for backwards-compat)
         try {
-          const reqHeaders: Record<string, string | string[] | undefined> = event.node.req.headers as any;
-          const existingSid = reqHeaders['mcp-session-id'] || reqHeaders['Mcp-Session-Id'];
-          if (!existingSid) {
-            (event.node.req.headers as any)['mcp-session-id'] = 'default-session';
+          const ver = String((event.node.req.headers['mcp-protocol-version'] as any) || '').trim();
+          if (ver && !['2025-06-18','2025-03-26','2024-11-05'].includes(ver)) {
+            setResponseStatus(event, 400);
+            try { event.node.res.setHeader('content-type','application/json'); } catch {}
+            return JSON.stringify({ jsonrpc: '2.0', error: { code: -32600, message: 'Unsupported MCP-Protocol-Version' }, id: null });
           }
         } catch {}
+
+        // Enforce session id for non-initialize requests
+        try {
+          const parsed = bodyBuf ? JSON.parse(bodyBuf.toString('utf-8')) : undefined;
+          const rpcMethod = parsed && typeof parsed === 'object' ? String(parsed.method || '') : '';
+          isInitialize = rpcMethod === 'initialize';
+        } catch {}
+        if (!isInitialize) {
+          const sidHeader = (event.node.req.headers['mcp-session-id'] as string | undefined) || '';
+          if (!sidHeader) {
+            setResponseStatus(event, 400);
+            try { event.node.res.setHeader('content-type', 'application/json'); } catch {}
+            return JSON.stringify({ jsonrpc: '2.0', error: { code: -32000, message: 'Missing Mcp-Session-Id header' }, id: null });
+          }
+        }
       }
 
       // Delegate to the SDK transport (writes to the Node response directly)
@@ -177,7 +197,7 @@ export async function startHttpServer(
     }
   }));
 
-  // Attach log ingest routes
+  // Attach log ingest routes (with optional token validation via header)
   app.use(createLogIngestRoutes(store, opts.logsRoute));
 
   // Health
@@ -203,7 +223,7 @@ export async function startHttpServer(
   await new Promise<void>((resolve) => nodeServer.listen(opts.port, opts.host, () => resolve()));
 
   // Advertise discovery so providers can auto-detect this server locally
-  await advertiseDiscovery(opts.host, opts.port, opts.logsRoute);
+  await advertiseDiscovery(opts.host, opts.port, opts.logsRoute, { projectRoot: process.cwd(), scope: 'http' });
 
   // eslint-disable-next-line no-console
   console.log(`MCP (Streamable HTTP) listening → http://${opts.host}:${opts.port}${opts.endpoint}`);
@@ -247,14 +267,18 @@ export async function startIngestOnlyServer(
 
   await new Promise<void>((resolve) => nodeServer.listen(opts.port, opts.host, () => resolve()));
 
+  // Determine the actual port assigned (when listening on port 0)
+  const addr = nodeServer.address() as any;
+  const actualPort = (addr && typeof addr === 'object' && 'port' in addr) ? (addr.port as number) : opts.port;
+
   // Advertise discovery for tooling that wants to auto-detect the ingest endpoint
-  await advertiseDiscovery(opts.host, opts.port, opts.logsRoute);
+  await advertiseDiscovery(opts.host, actualPort, opts.logsRoute, { projectRoot: process.cwd(), scope: 'stdio' });
 
   // eslint-disable-next-line no-console
-  console.log(`Log ingest endpoint        → http://${opts.host}:${opts.port}${opts.logsRoute}`);
+  console.error(`Log ingest endpoint        → http://${opts.host}:${actualPort}${opts.logsRoute}`);
 }
 
-async function advertiseDiscovery(host: string, port: number, logsRoute: `/${string}`) {
+async function advertiseDiscovery(host: string, port: number, logsRoute: `/${string}`, meta?: { projectRoot?: string; token?: string; scope?: 'http' | 'stdio' }) {
   try {
     const { writeFileSync } = await import('node:fs');
     const { join } = await import('node:path');
@@ -265,13 +289,14 @@ async function advertiseDiscovery(host: string, port: number, logsRoute: `/${str
       url: baseUrl,
       routeLogs: logsRoute,
       timestamp: Date.now(),
-      pid: typeof process !== 'undefined' ? process.pid : undefined
+      pid: typeof process !== 'undefined' ? process.pid : undefined,
+      projectRoot: meta?.projectRoot || process.cwd(),
+      token: meta?.token || undefined
     });
 
-    const files = [
-      join(process.cwd(), '.browser-echo-mcp.json'),
-      join(tmpdir(), 'browser-echo-mcp.json')
-    ];
+    const files = meta?.scope === 'http'
+      ? [ join(tmpdir(), 'browser-echo-mcp.json') ]
+      : [ join(process.cwd(), '.browser-echo-mcp.json'), join(tmpdir(), 'browser-echo-mcp.json') ];
 
     for (const f of files) {
       try { writeFileSync(f, payload); } catch {}
@@ -299,6 +324,30 @@ function createLogIngestRoutes(store: LogStore, logsRoute: `/${string}`) {
   // Log ingest (POST)
   router.post(logsRoute, defineEventHandler(async (event) => {
     try {
+      // Optional token check if discovery provided one (best-effort; disabled by default in dev)
+      try {
+        const { readFileSync, existsSync } = await import('node:fs');
+        const { join } = await import('node:path');
+        const { tmpdir } = await import('node:os');
+        const candidates = [join(process.cwd(), '.browser-echo-mcp.json'), join(tmpdir(), 'browser-echo-mcp.json')];
+        let requiredToken = '';
+        for (const p of candidates) {
+          try {
+            if (!existsSync(p)) continue;
+            const raw = readFileSync(p, 'utf-8');
+            const data = JSON.parse(raw);
+            if (data?.token) { requiredToken = String(data.token); break; }
+          } catch {}
+        }
+        if (requiredToken && process.env.BROWSER_ECHO_REQUIRE_TOKEN === '1') {
+          const got = String((event.node.req.headers['x-be-token'] as any) || '').trim();
+          if (!got || got !== requiredToken) {
+            setResponseStatus(event, 401);
+            return 'unauthorized';
+          }
+        }
+      } catch {}
+
       const raw = await readRawBody(event);
       const payload = typeof raw === 'string' ? JSON.parse(raw) : (raw ? JSON.parse(Buffer.from(raw as any).toString('utf-8')) : undefined);
       if (!payload || !Array.isArray(payload.entries)) {

packages/mcp/test/http.smoke.test.ts

@@ -46,6 +46,16 @@ describe('@browser-echo/mcp streamable HTTP transport (smoke)', () => {
     const body = await diag.text();
     expect(body).toContain('http smoke');
   });
+
+  it('returns 400 on invalid MCP-Protocol-Version header', async () => {
+    const res = await httpPost('/mcp', { jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }, { 'MCP-Protocol-Version': 'not-a-version' });
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 400 on non-initialize POST without Mcp-Session-Id', async () => {
+    const res = await httpPost('/mcp', { jsonrpc: '2.0', id: 2, method: 'tools/list' }, { 'MCP-Protocol-Version': '2025-06-18' });
+    expect(res.status).toBe(400);
+  });
 });
 
 

packages/mcp/test/stale.discovery.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { writeFileSync, existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('discovery file staleness', () => {
+  it('treats stale tmp discovery as invalid (over 60s or dead pid)', async () => {
+    const p = join(tmpdir(), 'browser-echo-mcp.json');
+    const payload = {
+      url: 'http://127.0.0.1:59999',
+      routeLogs: '/__client-logs',
+      timestamp: Date.now() - 120_000,
+      pid: 999999
+    };
+    try { writeFileSync(p, JSON.stringify(payload)); } catch {}
+    expect(existsSync(p)).toBe(true);
+    // The Vite/Next/Nuxt discovery readers ignore stale automatically; we cannot easily assert internal state here.
+    // This test ensures the file can be created; manual cleanup follows to avoid leaking state.
+    try { unlinkSync(p); } catch {}
+  });
+});
+
+

packages/mcp/test/stdio.multi.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync, readFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { McpTestClient } from './utils/mcpTestClient';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+describe('@browser-echo/mcp stdio transport — multiple editors', () => {
+  let c1: McpTestClient;
+  let c2: McpTestClient;
+  let c1Dir: string;
+  let c2Dir: string;
+
+  beforeAll(async () => {
+    const cli = join(__dirname, '..', 'bin', 'cli.mjs');
+    // Simulate two editors with separate working directories so discovery files don't collide
+    c1Dir = mkdtempSync(join(tmpdir(), 'be-multi-a-'));
+    c2Dir = mkdtempSync(join(tmpdir(), 'be-multi-b-'));
+    c1 = new McpTestClient({ cliEntryPoint: cli, env: { BROWSER_ECHO_INGEST_PORT: '0' }, cwd: c1Dir });
+    c2 = new McpTestClient({ cliEntryPoint: cli, env: { BROWSER_ECHO_INGEST_PORT: '0' }, cwd: c2Dir });
+    await c1.connect();
+    await c2.connect();
+  }, 30_000);
+
+  afterAll(async () => {
+    await c1?.close();
+    await c2?.close();
+  });
+
+  it('starts two stdio servers with different ingest ports (no conflict)', async () => {
+    const p1 = join(c1Dir, '.browser-echo-mcp.json');
+    const p2 = join(c2Dir, '.browser-echo-mcp.json');
+    // wait briefly
+    const start = Date.now();
+    while ((!existsSync(p1) || !existsSync(p2)) && (Date.now() - start) < 2000) {
+      await new Promise(r => setTimeout(r, 50));
+    }
+    const base1 = existsSync(p1) ? String(JSON.parse(readFileSync(p1, 'utf-8'))?.url || '').replace(/\/$/, '') : '';
+    const base2 = existsSync(p2) ? String(JSON.parse(readFileSync(p2, 'utf-8'))?.url || '').replace(/\/$/, '') : '';
+    expect(base1).toBeTruthy();
+    expect(base2).toBeTruthy();
+    expect(base1).not.toBe(base2);
+  });
+
+  it('logs sent to one ingest do not affect the other session buffer', async () => {
+    // Read each server's own discovery
+    const p1 = join(c1Dir, '.browser-echo-mcp.json');
+    const p2 = join(c2Dir, '.browser-echo-mcp.json');
+    const waitStart = Date.now();
+    while ((!existsSync(p1) || !existsSync(p2)) && (Date.now() - waitStart) < 2000) {
+      await new Promise(r => setTimeout(r, 50));
+    }
+    const d1 = existsSync(p1) ? JSON.parse(readFileSync(p1, 'utf-8')) : {};
+    const d2 = existsSync(p2) ? JSON.parse(readFileSync(p2, 'utf-8')) : {};
+    const base1 = String(d1?.url || '').replace(/\/$/, '');
+    const base2 = String(d2?.url || '').replace(/\/$/, '');
+    const route1 = d1?.routeLogs ? String(d1.routeLogs) : '/__client-logs';
+    const route2 = d2?.routeLogs ? String(d2.routeLogs) : '/__client-logs';
+    expect(base1).toBeTruthy();
+    expect(base2).toBeTruthy();
+
+    // Send two distinct sessions to their respective servers
+    const s1 = 'ed1torA1';
+    const s2 = 'ed1torB2';
+    await fetch(`${base1}${route1}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ sessionId: s1, entries: [{ level: 'info', text: 'multi A' }] }) });
+    await fetch(`${base2}${route2}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ sessionId: s2, entries: [{ level: 'info', text: 'multi B' }] }) });
+
+    // Poll a few times for eventual consistency
+    let aText = '', bText = '';
+    for (let i = 0; i < 8; i++) {
+      const a = await c1.callTool('get_logs', { session: s1, level: ['info','error','warn','log','debug'], includeStack: false, limit: 50 });
+      const b = await c2.callTool('get_logs', { session: s2, level: ['info','error','warn','log','debug'], includeStack: false, limit: 50 });
+      aText = String(a?.content?.[0]?.text || '');
+      bText = String(b?.content?.[0]?.text || '');
+      if (aText.includes('multi A') && bText.includes('multi B')) break;
+      await new Promise(r => setTimeout(r, 30));
+    }
+    expect(aText).toContain('multi A');
+    expect(bText).toContain('multi B');
+  });
+});
+
+