feat: enhance MCP server debugging and ingestion handling

- Added environment variable support for enabling debug logging in MCP server.
- Improved logging of MCP server startup context and environment variables for better traceability.
- Updated ingestion handling in Next.js and Nuxt.js to validate ACK responses, ensuring correct project and dev server identification.
- Refactored terminal output suppression logic based on remote ingest availability and explicit configuration settings.

Author: regenrek

.cursor/mcp.json

@@ -2,7 +2,10 @@
   "mcpServers": {
     "browser-echo-local": {
       "command": "node",
-      "args": ["packages/mcp/bin/cli.mjs"]
+      "args": ["packages/mcp/bin/cli.mjs"],
+      "env": {
+        "BROWSER_ECHO_DEBUG": "1"
+      }
     }
   }
 }

example/vue-vite-app/vite.config.ts

@@ -6,9 +6,7 @@ import browserEcho from '@browser-echo/vite'
 export default defineConfig({
   plugins: [vue(), browserEcho(
     {
-      stackMode: 'condensed',
-      network: { enabled: true },
-      mcp: { url: 'http://127.0.0.1:5179', suppressTerminal: true }
+      stackMode: 'condensed'
     },
   )],
 })

packages/mcp/src/server.ts

@@ -47,6 +47,39 @@ export async function startServer(
   server: McpServer,
   options: StartOptions,
 ): Promise<void> {
+  // Debug context: where and how this MCP server is started
+  const __debugEnabled = (() => {
+    try {
+      const v = String(process.env.BROWSER_ECHO_DEBUG ?? '').trim().toLowerCase();
+      return v !== '' && v !== '0' && v !== 'false';
+    } catch { return false; }
+  })();
+
+  if (__debugEnabled) {
+    try {
+      const envSnapshot: Record<string, string> = {};
+      for (const k of Object.keys(process.env)) {
+        if (k.startsWith('BROWSER_ECHO_') || k === 'NODE_ENV') {
+          const val = process.env[k];
+          envSnapshot[k] = typeof val === 'string' ? val : '';
+        }
+      }
+      const transport = options.type;
+      const host = transport === 'http' ? options.host : (options.host || '127.0.0.1');
+      const port = transport === 'http'
+        ? (options as any).port
+        : (() => {
+            const envIngest = process.env.BROWSER_ECHO_INGEST_PORT;
+            const preferred = ((options as any).port ?? (envIngest ? (Number(envIngest) | 0) : 5179)) | 0;
+            return preferred > 0 ? preferred : 5179;
+          })();
+      const route = transport === 'http' ? (options as any).logsRoute : ((options as any).logsRoute || '/__client-logs');
+      // eslint-disable-next-line no-console
+      console.error(`[MCP debug] pid=${process.pid} cwd=${process.cwd()} transport=${transport} host=${host} port=${port} route=${route}`);
+      // eslint-disable-next-line no-console
+      console.error(`[MCP debug] env: ${JSON.stringify(envSnapshot)}`);
+    } catch {}
+  }
   // Create store
   const bufferMax = Number(process.env.BROWSER_ECHO_BUFFER_SIZE ?? 1000) | 0;
   const store = new LogStore(bufferMax > 0 ? bufferMax : 1000);
@@ -273,19 +306,10 @@ export async function startHttpServer(
     throw err;
   }
 
-  // For Streamable HTTP, we intentionally do not write project JSON here. The per-project
-  // source of truth is written by the stdio ingest server only.
-
   // eslint-disable-next-line no-console
   console.log(`MCP (Streamable HTTP) listening → http://${opts.host}:${opts.port}${opts.endpoint}`);
   // eslint-disable-next-line no-console
   console.log(`Log ingest endpoint        → http://${opts.host}:${opts.port}${opts.logsRoute}`);
-  // Expose ingest discovery for other MCP instances in the same process tree
-  try {
-    process.env.BROWSER_ECHO_INGEST_BASE = `http://${opts.host}:${opts.port}`;
-    process.env.BROWSER_ECHO_LOGS_ROUTE = String(opts.logsRoute);
-    process.env.BROWSER_ECHO_INGEST_OWNER = '1';
-  } catch {}
 }
 
 /** Start a minimal HTTP server exposing ONLY:
@@ -390,18 +414,6 @@ export async function startIngestOnlyServer(
 
   // eslint-disable-next-line no-console
   console.error(`Log ingest endpoint        → http://${opts.host}:${actualPort}${opts.logsRoute}`);
-  // Write project-local discovery file for frameworks/tools to find ingest
-  try {
-    const discPath = join(process.cwd(), '.browser-echo-mcp.json');
-    const payload = { url: `http://${opts.host}:${actualPort}`, route: String(opts.logsRoute), timestamp: Date.now() };
-    writeFileSync(discPath, JSON.stringify(payload));
-  } catch {}
-  // Expose discovery for owner instance
-  try {
-    process.env.BROWSER_ECHO_INGEST_BASE = `http://${opts.host}:${actualPort}`;
-    process.env.BROWSER_ECHO_LOGS_ROUTE = String(opts.logsRoute);
-    process.env.BROWSER_ECHO_INGEST_OWNER = '1';
-  } catch {}
 }
 
 // Removed project JSON discovery in single-server mode
@@ -424,6 +436,15 @@ function createLogIngestRoutes(store: LogStore, logsRoute: `/${string}`) {
   // Log ingest (POST)
   router.post(logsRoute, defineEventHandler(async (event) => {
     try {
+      const __dbg = String(process.env.BROWSER_ECHO_DEBUG || '').trim().toLowerCase();
+      const __debug = __dbg !== '' && __dbg !== '0' && __dbg !== 'false';
+      if (__debug) {
+        try {
+          const hdrs = event.node.req.headers || {} as any;
+          // eslint-disable-next-line no-console
+          console.error('[MCP ingest debug] headers:', JSON.stringify(hdrs));
+        } 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)) {
@@ -435,10 +456,20 @@ function createLogIngestRoutes(store: LogStore, logsRoute: `/${string}`) {
       const hdrs = event.node.req.headers;
       const projectHeader = (hdrs['x-browser-echo-project-name'] || hdrs['x-project-name'] || hdrs['x-project'] || '') as string | string[] | undefined;
       const projectName = Array.isArray(projectHeader) ? String(projectHeader[0] || '') : String(projectHeader || '');
+      // Extract dev id for ACK handshake
+      const devIdHeader = (hdrs['x-browser-echo-dev-id'] || hdrs['x-dev-id'] || '') as string | string[] | undefined;
+      const devId = Array.isArray(devIdHeader) ? String(devIdHeader[0] || '') : String(devIdHeader || '');
+      if (__debug) {
+        try {
+          // eslint-disable-next-line no-console
+          console.error(`[MCP ingest debug] session=${sid} project=${projectName} devId=${devId} entries=${payload.entries.length}`);
+        } catch {}
+      }
       // Special command: remote clear request
       const isClear = payload.entries.length === 1 && String(payload.entries[0]?.text || '') === '__BROWSER_ECHO_CLEAR__';
       if (isClear) {
         store.clear({ session: sid ? String(sid).slice(0,8) : undefined, scope: 'hard', project: projectName || undefined });
+        try { event.node.res.setHeader('X-Browser-Echo-Ack', `project=${projectName || ''};devId=${devId || ''}`); } catch {}
         setResponseStatus(event, 204);
         return '';
       }
@@ -455,6 +486,10 @@ function createLogIngestRoutes(store: LogStore, logsRoute: `/${string}`) {
           project: projectName ? projectName : undefined
         });
       }
+      // Mark this instance as the ingest owner so clients can distinguish our server from stray ones
+      try { event.node.res.setHeader('X-Browser-Echo-Ack', `project=${projectName || ''};devId=${devId || ''};owner=1`); } catch {}
+      // Mark this instance as the ingest owner so clients can distinguish our server from stray ones
+      try { event.node.res.setHeader('X-Browser-Echo-Ack', `project=${projectName || ''};devId=${devId || ''};owner=1`); } catch {}
       setResponseStatus(event, 204);
       return '';
     } catch {

packages/next/src/route.ts

@@ -2,28 +2,7 @@ import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
 
 const MCP_BASE = (process.env.BROWSER_ECHO_MCP_URL || 'http://127.0.0.1:5179').replace(/\/$/, '').replace(/\/mcp$/i, '');
-let __probeStarted = false;
-async function __probeHealthOnce(): Promise<boolean> {
-  try {
-    const ctrl = new AbortController();
-    const t = setTimeout(() => ctrl.abort(), 400);
-    const res = await fetch(`${MCP_BASE}/health`, { signal: ctrl.signal as any, cache: 'no-store' as any });
-    clearTimeout(t);
-    return !!res && res.ok;
-  } catch { return false; }
-}
-function __startHealthProbe() {
-  if (__probeStarted) return;
-  __probeStarted = true;
-  setInterval(async () => {
-    if (__hasForwardedOnce) return;
-    const ok = await __probeHealthOnce();
-    if (ok) __hasForwardedOnce = true;
-  }, 1500);
-}
-__startHealthProbe();
-
-// Simplified: fixed single-server URL or env override
+// Fixed single-server URL or env override; suppression relies on ACK, not health probes
 
 export type BrowserLogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
 type Entry = { level: BrowserLogLevel | string; text: string; time?: number; stack?: string; source?: string; };
@@ -32,8 +11,22 @@ type Payload = { sessionId?: string; entries: Entry[] };
 export const runtime = 'nodejs';
 export const dynamic = 'force-dynamic';
 
-// Module-scope: suppress only after first confirmed forward (any 2xx)
-let __hasForwardedOnce = false;
+// Module-scope: track MCP availability via ACK; unsuppress on failures
+let __isRemoteAvailable = false;
+let __nextDevInstanceId: string | null = null;
+function getOrCreateDevId(): string {
+  if (__nextDevInstanceId) return __nextDevInstanceId;
+  try {
+    // @ts-ignore: webcrypto may exist in Node 20+
+    const wc = (globalThis as any).crypto?.getRandomValues ? (globalThis as any).crypto : require('node:crypto').webcrypto;
+    const a = new Uint8Array(8);
+    wc.getRandomValues(a);
+    __nextDevInstanceId = Array.from(a).map((b) => b.toString(16).padStart(2,'0')).join('');
+  } catch {
+    __nextDevInstanceId = String(Math.random()).slice(2, 10);
+  }
+  return __nextDevInstanceId;
+}
 
 export async function POST(req: NextRequest) {
   let payload: Payload | null = null;
@@ -44,26 +37,65 @@ export async function POST(req: NextRequest) {
   const baseUrl = MCP_BASE;
   const mcp = { url: baseUrl, routeLogs: '/__client-logs' } as const;
 
-  // Forward to MCP server (fire-and-forget) and update connection state
+  // Forward to MCP server (fire-and-forget) and update availability based on ACK
   try {
     const route = (mcp.routeLogs as `/${string}`) || '/__client-logs';
     const headers: Record<string,string> = { 'content-type': 'application/json' };
     const projectName = (process.env.BROWSER_ECHO_PROJECT_NAME || (process.env.npm_package_name || '')).trim();
     if (projectName) headers['X-Browser-Echo-Project-Name'] = projectName;
+    const devId = getOrCreateDevId();
+    headers['X-Browser-Echo-Dev-Id'] = devId;
+
     const ctrl = new AbortController();
     const timeout = setTimeout(() => ctrl.abort(), 500);
+
     fetch(`${mcp.url}${route}`, {
       method: 'POST',
       headers,
       body: JSON.stringify(payload),
       keepalive: true,
       cache: 'no-store',
       signal: ctrl.signal as any,
-    }).then((res) => { try { clearTimeout(timeout); } catch {} if (res && res.ok) __hasForwardedOnce = true; }).catch(() => { try { clearTimeout(timeout); } catch {} });
+    }).then((res) => {
+      try { clearTimeout(timeout); } catch {}
+      const ok = !!res && res.ok;
+      let ackOk = false;
+      try {
+        const ack = (res as any).headers?.get?.('X-Browser-Echo-Ack') || '';
+        if (ack) {
+          const mProject = /project=([^;]*)/i.exec(ack);
+          const mDev = /devId=([^;]*)/i.exec(ack);
+          const mOwner = /owner=([^;]*)/i.exec(ack);
+          const aProject = mProject ? decodeURIComponent(mProject[1]) : '';
+          const aDev = mDev ? decodeURIComponent(mDev[1]) : '';
+          const isOwner = (mOwner ? String(mOwner[1]) : '') === '1';
+          ackOk = (!projectName || aProject === projectName) && aDev === devId && isOwner;
+        }
+      } catch {}
+      if (ok && ackOk) {
+        __isRemoteAvailable = true;
+      } else {
+        __isRemoteAvailable = false;
+      }
+    }).catch(() => {
+      try { clearTimeout(timeout); } catch {}
+      __isRemoteAvailable = false;
+    });
   } catch {}
 
-  // Print locally until first confirmed forward; then suppress
-  const shouldPrint = !__hasForwardedOnce;
+  // Terminal printing policy for Next route:
+  // - Default: ALWAYS print locally
+  // - If BROWSER_ECHO_SUPPRESS_TERMINAL=1|true, suppress when remote ingest is confirmed available
+  // - If BROWSER_ECHO_SUPPRESS_TERMINAL=0|false, always print
+  const envSup = String(process.env.BROWSER_ECHO_SUPPRESS_TERMINAL ?? '').trim().toLowerCase();
+  const envForceSuppress = envSup === '1' || envSup === 'true';
+  const envForcePrint = envSup === '0' || envSup === 'false';
+  let shouldPrint = true;
+  if (envForcePrint) {
+    shouldPrint = true;
+  } else if (envForceSuppress) {
+    shouldPrint = !__isRemoteAvailable;
+  }
 
   const sid = (payload.sessionId ?? 'anon').slice(0, 8);
   for (const entry of payload.entries) {