refactor: update MCP server configuration and enhance project logging capabilities

- Renamed "browser-echo" to "browser-echo-local" in .cursor/mcp.json for clarity.
- Removed obsolete .browser-echo-mcp.json file to streamline configuration.
- Improved transport auto-detection logic in index.ts to prefer Streamable HTTP when running interactively.
- Added project metadata handling in log entries and filtering capabilities for logs based on project name.
- Simplified MCP server resolution in route handlers for Next.js and Nuxt.js to use environment variables or defaults.
- Enhanced log retrieval and clearing tools to support project-specific operations.

Author: regenrek

.cursor/mcp.json

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

packages/mcp/.browser-echo-mcp.json

@@ -41,10 +41,12 @@ const cli = defineCommand({
       process.env.BROWSER_ECHO_BUFFER_SIZE = String(args.buffer);
     }
 
-    // Determine transport: stdio by default, or HTTP if --http or network options provided
-    const useHttp = args.http 
-      || args.port !== '5179' || args.host !== '127.0.0.1' 
-      || args.endpoint !== '/mcp' || args.logsRoute !== '/__client-logs';
+    // Transport auto-detection:
+    // - Prefer Streamable HTTP when running interactively in a terminal (TTY)
+    // - Fall back to stdio when not attached to a TTY (e.g., spawned by an editor/agent)
+    // - Respect --http to force HTTP regardless of TTY
+    const isInteractiveTty = Boolean((process as any).stdout?.isTTY) && Boolean((process as any).stdin?.isTTY);
+    const useHttp = Boolean(args.http) || isInteractiveTty;
 
     // Start server with selected transport. Prefer 5179 for ingest if stdio.
     await startServer(mcp, useHttp ? {
@@ -116,6 +118,7 @@ export function publishLogEntry(entry: {
   source?: string;
   stack?: string;
   tag?: string;
+  project?: string;
 }): void {
   if (!entry.text || !entry.level) {
     console.error('[browser-echo] Missing required fields for publishLogEntry');
@@ -129,7 +132,8 @@ export function publishLogEntry(entry: {
     time: entry.time ?? Date.now(),
     source: entry.source,
     stack: entry.stack,
-    tag: entry.tag || '[browser]'
+    tag: entry.tag || '[browser]',
+    project: entry.project
   };
   if (!activeStore) {
     console.error('[browser-echo] No active MCP server to publish log entry');

packages/mcp/src/index.ts

@@ -7,12 +7,14 @@ export const GetLogsArgs = {
   includeStack: z.boolean().optional().default(false).describe('Include stack traces in text view'),
   limit: z.number().int().min(1).max(5000).optional().describe('Max number of entries to return'),
   contains: z.string().optional().describe('Substring filter on entry.text'),
-  sinceMs: z.number().nonnegative().optional().describe('Only entries with time >= sinceMs')
+  sinceMs: z.number().nonnegative().optional().describe('Only entries with time >= sinceMs'),
+  project: z.string().optional().describe('Project name to filter logs')
 } satisfies z.ZodRawShape;
 
 export const ClearLogsArgs = {
   session: z.string().optional().describe('8-char session id prefix to clear only one session'),
-  scope: z.enum(['soft','hard']).optional().default('hard').describe('soft: set baseline (non-destructive), hard: delete entries')
+  scope: z.enum(['soft','hard']).optional().default('hard').describe('soft: set baseline (non-destructive), hard: delete entries'),
+  project: z.string().optional().describe('Project name to clear only that project\'s logs')
 } satisfies z.ZodRawShape;
 
 // Full Zod objects for local inference/validation

packages/mcp/src/schemas/logs.ts

@@ -88,8 +88,6 @@ export async function stopServer(server: McpServer) {
     console.error('Error occurred during server stop:', error);
   }
   finally {
-    // Best-effort cleanup of project JSON
-    try { rmSync(joinPath(process.cwd(), '.browser-echo-mcp.json'), { force: true }); } catch {}
     process.exit(0);
   }
 }
@@ -224,7 +222,27 @@ export async function startHttpServer(
     });
   } catch {}
 
-  await new Promise<void>((resolve) => nodeServer.listen(opts.port, opts.host, () => resolve()));
+  // Attempt to listen on the requested port (fail fast if already in use)
+  try {
+    await new Promise<void>((resolve, reject) => {
+      nodeServer.listen(opts.port, opts.host, () => resolve());
+      nodeServer.on('error', reject);
+    });
+  } catch (err: any) {
+    const isAddrInUse = err && (err.code === 'EADDRINUSE' || String(err.message || '').includes('EADDRINUSE'));
+    if (isAddrInUse) {
+      const errorMsg = [
+        `Failed to start MCP server: Port ${opts.port} is already in use.`,
+        `Another instance may be running. Please either:`,
+        `  - Stop the other instance, or`,
+        `  - Use a different port with --port flag`
+      ].join('\n');
+      console.error(errorMsg);
+      process.exit(1);
+    }
+    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.
 
@@ -299,7 +317,7 @@ export async function startIngestOnlyServer(
     });
   }
 
-  // Prefer requested port (usually 5179); fall back to ephemeral if it's taken
+  // Prefer requested port (usually 5179); do not fall back (single-server mode)
   let nodeServer = createNodeServer(toNodeListener(app));
   configureNodeServer(nodeServer);
 
@@ -308,33 +326,19 @@ export async function startIngestOnlyServer(
     actualPort = await listenWithResult(nodeServer, opts.host, opts.port);
   } catch (err: any) {
     const isAddrInUse = err && (err.code === 'EADDRINUSE' || String(err.message || '').includes('EADDRINUSE'));
-    if (isAddrInUse && opts.port !== 0) {
-      try { nodeServer.close?.(); } catch {}
-      nodeServer = createNodeServer(toNodeListener(app));
-      configureNodeServer(nodeServer);
-      actualPort = await listenWithResult(nodeServer, opts.host, 0);
-    } else {
-      throw err;
+    if (isAddrInUse) {
+      const base = `http://${opts.host}:${opts.port}`;
+      // eslint-disable-next-line no-console
+      console.error(`Failed to start ingest-only server: Port in use at ${base}${opts.logsRoute}`);
     }
+    throw err;
   }
 
-  // Write project-local config for providers
-  writeProjectJson(opts.host, actualPort, opts.logsRoute);
-
   // eslint-disable-next-line no-console
   console.error(`Log ingest endpoint        → http://${opts.host}:${actualPort}${opts.logsRoute}`);
 }
 
-function writeProjectJson(host: string, port: number, route: `/${string}`) {
-  try {
-    const baseUrl = `http://${host}:${port}`;
-    const payload = JSON.stringify({ url: baseUrl, route, timestamp: Date.now(), pid: typeof process !== 'undefined' ? process.pid : undefined });
-    const file = joinPath(process.cwd(), '.browser-echo-mcp.json');
-    const tmp = file + '.tmp';
-    try { writeFileSync(tmp, payload); renameSync(tmp, file); }
-    catch { try { writeFileSync(file, payload); } catch {} }
-  } catch {}
-}
+// Removed project JSON discovery in single-server mode
 
 /** Create log ingest routes that can be attached to any H3 app */
 function createLogIngestRoutes(store: LogStore, logsRoute: `/${string}`) {
@@ -361,6 +365,10 @@ function createLogIngestRoutes(store: LogStore, logsRoute: `/${string}`) {
         return 'invalid payload';
       }
       const sid = String(payload.sessionId ?? 'anon');
+      // Extract optional project metadata from headers
+      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 || '');
       for (const entry of payload.entries as Array<{ level: BrowserLogLevel | string; text: string; time?: number; stack?: string; source?: string; }>) {
         const level = normalizeLevel(entry.level);
         store.append({
@@ -370,7 +378,8 @@ function createLogIngestRoutes(store: LogStore, logsRoute: `/${string}`) {
           time: entry.time,
           source: entry.source,
           stack: entry.stack,
-          tag: '[browser]'
+          tag: '[browser]',
+          project: projectName ? projectName : undefined
         });
       }
       setResponseStatus(event, 204);

packages/mcp/src/server.ts

@@ -8,6 +8,8 @@ export interface LogEntry {
   source?: string;
   stack?: string;
   tag?: string;
+  /** Optional project name/identifier for multi-project segregation */
+  project?: string;
 }
 
 const DEFAULT_BUFFER = 1000;

packages/mcp/src/store.ts

@@ -11,13 +11,30 @@ export function registerClearLogsTool(ctx: McpToolContext) {
     ClearLogsSchema,
     async (args, _extra) => {
       const safeArgs = args || {} as any;
-      const { session, scope = 'hard' } = safeArgs;
+      const { session, scope = 'hard', project } = safeArgs as typeof ClearLogsSchema['_output'];
       const validSession = validateSessionId(session);
-      store.clear({ session: validSession, scope });
+      if (project) {
+        // Project-scoped hard clear by filtering entries not matching the project
+        // For soft clear, set baseline without deleting
+        if (scope === 'soft') {
+          // Use global baseline for project-scoped soft clear by current time; retrieval filters by project
+          // This keeps implementation simple while honoring freshness for the project
+          store.clear({ scope: 'soft' });
+        } else {
+          // Rebuild entries array excluding the project. Since entries is private, leverage snapshot and re-append
+          const remaining = store.snapshot().filter(e => (e.project || '') !== project);
+          // Replace internal state: simulate with hard clear then re-append
+          store.clear({ scope: 'hard' });
+          for (const e of remaining) store.append(e);
+        }
+      } else {
+        store.clear({ session: validSession, scope });
+      }
 
       let message = 'Browser log buffer ';
       message += scope === 'soft' ? 'baseline set' : 'cleared';
-      if (validSession) message += ` for session ${validSession}`;
+      if (project) message += ` for project ${project}`;
+      else if (validSession) message += ` for session ${validSession}`;
       message += '.';
 
       return { content: [{ type: 'text' as const, text: message }] };

packages/mcp/src/tools/clearLogs.ts

@@ -18,8 +18,9 @@ export function registerGetLogsTool(ctx: McpToolContext) {
         includeStack = false,
         limit = 1000,
         contains,
-        sinceMs
-      } = safeArgs;
+        sinceMs,
+        project
+      } = safeArgs as typeof GetLogsSchema['_output'];
 
       const validSession = validateSessionId(session);
       const validSince = typeof sinceMs === 'number' && sinceMs >= 0 ? sinceMs : undefined;
@@ -28,23 +29,85 @@ export function registerGetLogsTool(ctx: McpToolContext) {
       let items = store.snapshot(validSession);
       if (validSince) items = items.filter(e => !e.time || e.time >= validSince);
       if (level?.length) items = items.filter(e => level.includes(e.level));
+      if (project) items = items.filter(e => (e.project || '') === project);
       if (contains) items = items.filter(e => (e.text || '').includes(contains));
       const final = includeStack ? items : items.map(e => ({ ...e, stack: '' }));
 
-      const limited = limit && final.length > limit ? final.slice(-limit) : final;
-
-      const text = limited.map(e => {
-        const sid = (e.sessionId || 'anon').slice(0, 8);
-        const lvl = (e.level || 'log').toUpperCase();
-        const tag = e.tag || '[browser]';
-        let line = `${tag} [${sid}] ${lvl}: ${e.text}`;
-        if (e.source) line += ` (${e.source})`;
-        if (includeStack && e.stack?.trim()) {
-          const indented = e.stack.split(/\r?\n/g).map(l => l ? `    ${l}` : l).join('\n');
-          return `${line}\n${indented}`;
+      // Auto-select a single active project by recency when no project is specified
+      let autoProject: string | undefined;
+      if (!project) {
+        const projectsAll = new Set(final.map(e => e.project || '')); projectsAll.delete('');
+        if (projectsAll.size > 1) {
+          const latestByProject: Record<string, number> = {};
+          for (const e of final) {
+            const p = e.project || '';
+            if (!p) continue;
+            const t = e.time || 0;
+            if (!latestByProject[p] || t > latestByProject[p]) latestByProject[p] = t;
+          }
+          const now = Date.now();
+          const recentWindowMs = 60_000; // 60s window for "active" project
+          const active = Object.entries(latestByProject)
+            .filter(([, t]) => t > 0 && (now - t) <= recentWindowMs)
+            .map(([p]) => p);
+          if (active.length === 1) autoProject = active[0];
         }
-        return line;
-      }).join('\n');
+      }
+
+      const baseForOutput = autoProject ? final.filter(e => (e.project || '') === autoProject) : final;
+      const limited = limit && baseForOutput.length > limit ? baseForOutput.slice(-limit) : baseForOutput;
+
+      // Multi-project awareness: if no explicit project and multiple projects exist, show grouped preview
+      const uniqueProjects = new Set(limited.map(e => e.project || '')); uniqueProjects.delete('');
+      let text: string;
+      if (!project && !autoProject && uniqueProjects.size > 1) {
+        const groups = Array.from(uniqueProjects.values());
+        const byProject: Record<string, typeof limited> = {};
+        for (const p of groups) byProject[p] = [];
+        for (const e of limited) {
+          const key = e.project || '';
+          if (key) byProject[key].push(e);
+        }
+        // Heuristic: order by most recent entry time desc
+        const sortedProjects = groups.sort((a, b) => {
+          const at = (byProject[a].at(-1)?.time || 0);
+          const bt = (byProject[b].at(-1)?.time || 0);
+          return bt - at;
+        });
+        const previewPerProject = 5;
+        const sections: string[] = [];
+        for (const p of sortedProjects) {
+          const entries = byProject[p];
+          const preview = entries.slice(-previewPerProject).map(e => {
+            const sid = (e.sessionId || 'anon').slice(0, 8);
+            const lvl = (e.level || 'log').toUpperCase();
+            const tag = e.tag || '[browser]';
+            let line = `[${p}] ${tag} [${sid}] ${lvl}: ${e.text}`;
+            if (e.source) line += ` (${e.source})`;
+            if (includeStack && e.stack?.trim()) {
+              const indented = e.stack.split(/\r?\n/g).map(l => l ? `    ${l}` : l).join('\n');
+              return `${line}\n${indented}`;
+            }
+            return line;
+          }).join('\n');
+          sections.push(`${p} – ${entries.length} entries (use get_logs with { project: "${p}" } for full list):\n${preview}`);
+        }
+        text = sections.join('\n\n');
+      } else {
+        text = limited.map(e => {
+          const sid = (e.sessionId || 'anon').slice(0, 8);
+          const lvl = (e.level || 'log').toUpperCase();
+          const projectTag = e.project ? `[${e.project}]` : '';
+          const tag = e.tag || '[browser]';
+          let line = `${projectTag ? projectTag + ' ' : ''}${tag} [${sid}] ${lvl}: ${e.text}`;
+          if (e.source) line += ` (${e.source})`;
+          if (includeStack && e.stack?.trim()) {
+            const indented = e.stack.split(/\r?\n/g).map(l => l ? `    ${l}` : l).join('\n');
+            return `${line}\n${indented}`;
+          }
+          return line;
+        }).join('\n');
+      }
 
       return {
         content: [

packages/mcp/src/tools/getLogs.ts

@@ -1,7 +1,7 @@
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
 
-// Simplified: resolve MCP from project-local JSON once; no fallback
+// Simplified: fixed single-server URL or env override
 
 export type BrowserLogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
 type Entry = { level: BrowserLogLevel | string; text: string; time?: number; stack?: string; source?: string; };
@@ -16,14 +16,17 @@ export async function POST(req: NextRequest) {
   catch { return new NextResponse('invalid JSON', { status: 400 }); }
   if (!payload || !Array.isArray(payload.entries)) return new NextResponse('invalid payload', { status: 400 });
 
-  // Resolve MCP once: project JSON only (no fallback)
-  const mcp = await __resolveMcpFromProject();
+  // Fixed resolution (single-server): env or default localhost:5179
+  const mcp = { url: (process.env.BROWSER_ECHO_MCP_URL || 'http://127.0.0.1:5179').replace(/\/$/, ''), routeLogs: '/__client-logs' } as const;
 
   // Forward to MCP server if available (fire-and-forget)
   if (mcp.url) {
     try {
       const route = (mcp.routeLogs as `/${string}`) || '/__client-logs';
       const headers: Record<string,string> = { 'content-type': 'application/json' };
+      // Derive project name from env or package name
+      const projectName = (process.env.BROWSER_ECHO_PROJECT_NAME || (process.env.npm_package_name || '')).trim();
+      if (projectName) headers['X-Browser-Echo-Project-Name'] = projectName;
       fetch(`${mcp.url}${route}`, {
         method: 'POST',
         headers,
@@ -74,41 +77,3 @@ function color(level: BrowserLogLevel, msg: string) {
   }
 }
 function dim(s: string) { return c.dim + s + c.reset; }
-
-async function __resolveMcpFromProject(): Promise<{ url: string; routeLogs?: `/${string}` }> {
-  try {
-    const { readFileSync, existsSync } = await import('node:fs');
-    const { join, dirname } = await import('node:path');
-    let dir = process.cwd();
-    for (let depth = 0; depth < 10; depth++) {
-      const p = join(dir, '.browser-echo-mcp.json');
-      if (existsSync(p)) {
-        const raw = readFileSync(p, 'utf-8');
-        const data = JSON.parse(raw);
-        const rawUrl = (data?.url ? String(data.url) : '');
-        const base = rawUrl.replace(/\/$/, '').replace(/\/mcp$/i, '');
-        if (!/^(http:\/\/127\.0\.0\.1|http:\/\/localhost)/.test(base)) break;
-        const routeLogs = (data?.route ? String(data.route) : '/__client-logs') as `/${string}`;
-        if (base && await __pingHealth(`${base}/health`, 250)) {
-          return { url: base, routeLogs };
-        }
-      }
-      const up = dirname(dir);
-      if (up === dir) break;
-      dir = up;
-    }
-  } catch {}
-  return { url: '' } as any;
-}
-
-async function __pingHealth(url: string, timeoutMs: number): Promise<boolean> {
-  try {
-    const ctrl = new AbortController();
-    const t = setTimeout(() => ctrl.abort(), timeoutMs);
-    const res = await fetch(url, { signal: ctrl.signal, cache: 'no-store' as any });
-    clearTimeout(t);
-    return res.ok;
-  } catch {
-    return false;
-  }
-}