docs: update README files and enhance MCP server integration details

- Updated BROWSER_ECHO_MCP_URL in README files to remove the '/mcp' suffix for clarity.
- Improved documentation on environment variables and server route integration for various frameworks (React, Next.js, Nuxt, Vite, Vue).
- Enhanced descriptions for log retrieval and clearing functionalities, including project-specific operations.
- Streamlined instructions for setting up MCP server connections across different environments.

Author: regenrek

packages/core/README.md

@@ -93,7 +93,7 @@ For core usage, MCP forwarding depends on your server-side route implementation.
 
 ### Environment Variables
 
-- `BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp` — Set in your server environment
+- `BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179` — Set in your server environment
 - `BROWSER_ECHO_SUPPRESS_TERMINAL=1` — Control terminal output in your route handler
 
 ### Server Route MCP Integration

packages/mcp/README.md

@@ -288,160 +288,63 @@ Best for local development with AI assistants:
 }
 ```
 
-In stdio mode:
-- MCP communication happens over **stdio** (no HTTP MCP endpoint)
-- An **HTTP ingest server** runs on a local port (127.0.0.1) for browsers to POST logs
-- The actual URL is written to `.browser-echo-mcp.json` in your project root
-- Console output (stderr): `MCP (stdio) listening on stdio (ingest HTTP active)`
-
-### HTTP Mode
-
-For web-based AI tools or when you need HTTP MCP access:
-
-```json
-// .cursor/mcp.json  
-{
-  "mcpServers": {
-    "browser-echo": {
-      "command": "node", 
-      "args": ["packages/mcp/bin/cli.mjs", "--http"]
-    }
-  }
-}
-```
-
-In HTTP mode:
-- 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 (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
-```
+- Vite/Next/Nuxt send `X-Browser-Echo-Project-Name` so logs are project-tagged.
+- No `.browser-echo-mcp.json` discovery files are used anymore.
 
 ---
 
-## How Logs Reach the Server
-
-### Browser → Ingest (Recommended)
-
-Your framework packages automatically send logs to the ingest endpoint:
+## Available Tools
 
-```typescript
-// Browser automatically POSTs to ingest endpoint
-POST http://127.0.0.1:5179/__client-logs
-{
-  "sessionId": "tab-123",
-  "entries": [
-    { 
-      "level": "error", 
-      "text": "Failed to fetch user", 
-      "time": 1724200000000, 
-      "source": "api.ts:42", 
-      "stack": "Error: ..." 
-    }
-  ]
-}
-```
+### `get_logs` — Fetch Frontend Browser Logs
 
-### Framework Forwarding
+Key params (selection):
+- `project?: string` — filter by project name
+- `level?: string[]`, `sinceMs?: number`, `contains?: string`
+- `session?: string`, `includeStack?: boolean`, `limit?: number`
+- `autoBaseline?: boolean` (default true)
+- `stackedMode?: boolean` (default false) — disables auto-baseline
 
-Framework packages (Next.js, Nuxt, etc.) can forward logs to the MCP server:
+Adaptive output:
+- If multiple projects are active and no `project` specified, returns grouped previews per project with counts and a tip to filter.
 
-```bash
-# Set this in your app's environment
-export BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp
-```
+### `clear_logs` — Clear Frontend Browser Logs
 
-When set, framework handlers automatically forward browser logs to the MCP ingest endpoint.
+- Supports `project?: string` to clear only that project’s logs.
+- `scope: 'soft' | 'hard'` for baselining vs deletion.
 
 ---
 
 ## Programmatic API
 
-Start the MCP server programmatically in your Node.js application:
-
-```typescript
+```ts
 import { startMcpServer, publishLogEntry } from '@browser-echo/mcp';
 
-// Start HTTP MCP server in-process
-await startMcpServer({
-  name: 'My App Logs',
-  version: '1.0.0',
-  bufferSize: 2000,
-  host: '127.0.0.1',
-  port: 5179,
-  endpoint: '/mcp',
-  logsRoute: '/__client-logs'
-});
+await startMcpServer({ host: '127.0.0.1', port: 5179, endpoint: '/mcp', logsRoute: '/__client-logs' });
 
-// Publish log entries programmatically
 publishLogEntry({
   sessionId: 'user-123',
   level: 'error',
   text: 'Failed to fetch user data',
   time: Date.now(),
-  source: 'api.ts:42',
-  stack: 'Error: Failed to fetch...',
-  tag: '[api]'
+  tag: '[api]',
+  project: 'my-app'
 });
 ```
 
-> **Note:** If `BROWSER_ECHO_MCP_URL` is set, `startMcpServer()` becomes a no-op to avoid duplicate servers.
-
 ---
 
 ## Environment Variables
 
-Configure the MCP server behavior with these environment variables:
-
-- `BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp` — MCP server URL for framework forwarding (if set, frameworks bypass auto-discovery)
-- `BROWSER_ECHO_BUFFER_SIZE=1000` — Max entries kept in memory (default: `1000`)
-- `BROWSER_ECHO_INGEST_PORT=5179` — Force a fixed ingest port in stdio mode (default: 5179)
-- `BROWSER_ECHO_SUPPRESS_TERMINAL=1` — Force suppress terminal output when MCP is forwarding logs
-- `BROWSER_ECHO_SUPPRESS_TERMINAL=0` — Force show terminal output even when MCP is active
-
----
-
-## Common Workflows
-
-### Debug Hydration Errors
-```
-1. User: "Clear logs and let me reproduce the hydration error"
-   → clear_logs({ scope: 'soft' })
-2. User reproduces the issue in browser
-3. User: "Check for hydration errors"  
-   → get_logs({ level: ['error', 'warn'], contains: 'hydration' })
-```
-
-### Monitor Specific Browser Tab
-```
-1. User: "Show me all active sessions"
-   → get_logs() // Look for unique session IDs
-2. User: "Focus on session starting with 'a1b2'"
-   → get_logs({ session: 'a1b2' })
-```
-
-### Fresh Error Capture
-```
-1. clear_logs({ scope: 'soft' })  // Set baseline
-2. Run tests or reproduce issue
-3. get_logs({ level: ['error', 'warn'] })  // Only new errors
-```
+- `BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp` — Frameworks forward logs here
+- `BROWSER_ECHO_PROJECT_NAME` — Label logs by project
+- `BROWSER_ECHO_BUFFER_SIZE=1000` — Ring buffer size
 
 ---
 
 ## Security
 
-**Local Development Defaults:**
-- CORS headers are permissive (`Access-Control-Allow-Origin: *`) 
-- Binds to `127.0.0.1` by default for local-only access
-- When exposing over network, add authentication/proxy as needed
+- Binds to `127.0.0.1` by default
+- CORS permissive for local dev; add auth/proxy if exposing
 
 ---
 

packages/mcp/src/schemas/logs.ts

@@ -8,7 +8,9 @@ export const GetLogsArgs = {
   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'),
-  project: z.string().optional().describe('Project name to filter logs')
+  project: z.string().optional().describe('Project name to filter logs'),
+  autoBaseline: z.boolean().optional().default(true).describe('Automatically baseline after retrieval to show only new logs next time'),
+  stackedMode: z.boolean().optional().default(false).describe('Disable auto-baseline to accumulate logs across calls')
 } satisfies z.ZodRawShape;
 
 export const ClearLogsArgs = {

packages/mcp/src/server.ts

@@ -1,6 +1,4 @@
 import { createServer as createNodeServer } from 'node:http';
-import { writeFileSync, rmSync, renameSync } from 'node:fs';
-import { join as joinPath } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 import { createApp, createRouter, defineEventHandler, getQuery, readRawBody, setResponseStatus, toNodeListener } from 'h3';
@@ -101,6 +99,31 @@ export async function startHttpServer(
   store: LogStore,
   opts: { host: string; port: number; endpoint: `/${string}`; logsRoute: `/${string}` }
 ): Promise<void> {
+  async function tryFetch(url: string, init: any = {}, timeoutMs = 400): Promise<{ ok: boolean; status: number; text?: string }> {
+    try {
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), timeoutMs);
+      const res = await fetch(url, { ...(init || {}), signal: ctrl.signal as any, cache: 'no-store' as any });
+      clearTimeout(t);
+      let body: string | undefined;
+      try { body = await res.text(); } catch {}
+      return { ok: !!res.ok, status: res.status, text: body };
+    } catch {
+      return { ok: false, status: 0 } as any;
+    }
+  }
+
+  async function isExistingHttpMcp(base: string, endpoint: `/${string}`): Promise<boolean> {
+    const health = await tryFetch(`${base}/health`);
+    if (!health.ok) return false;
+    // Probe MCP endpoint: GET without session should respond 405 with JSON error
+    const probe = await tryFetch(`${base}${endpoint}`, { method: 'GET' });
+    if (probe.status === 405 && (probe.text || '').includes('Method not allowed')) return true;
+    // Some servers may not expose GET; try OPTIONS as a weak signal
+    const opt = await tryFetch(`${base}${endpoint}`, { method: 'OPTIONS' });
+    return opt.status === 204 || opt.status === 200;
+  }
+
   const app = createApp();
   const router = createRouter();
 
@@ -231,11 +254,16 @@ export async function startHttpServer(
   } catch (err: any) {
     const isAddrInUse = err && (err.code === 'EADDRINUSE' || String(err.message || '').includes('EADDRINUSE'));
     if (isAddrInUse) {
+      const base = `http://${opts.host}:${opts.port}`;
+      const reuse = await isExistingHttpMcp(base, opts.endpoint);
+      if (reuse) {
+        // eslint-disable-next-line no-console
+        console.error(`Existing MCP server detected at ${base}. Reusing it without starting a new instance.`);
+        return; // Treat as successful startup (server already available)
+      }
       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`
+        `Failed to start MCP server: Port ${opts.port} is already in use by a non-MCP service.`,
+        `Either stop that service or choose a different port with --port.`,
       ].join('\n');
       console.error(errorMsg);
       process.exit(1);
@@ -328,6 +356,18 @@ export async function startIngestOnlyServer(
     const isAddrInUse = err && (err.code === 'EADDRINUSE' || String(err.message || '').includes('EADDRINUSE'));
     if (isAddrInUse) {
       const base = `http://${opts.host}:${opts.port}`;
+      // If an ingest server already responds to /health, reuse it silently
+      try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 400);
+        const res = await fetch(`${base}/health`, { signal: ctrl.signal as any, cache: 'no-store' as any });
+        clearTimeout(t);
+        if (res && res.ok) {
+          // eslint-disable-next-line no-console
+          console.error(`Ingest server already running at ${base}${opts.logsRoute}. Reusing existing instance.`);
+          return; // Treat as success
+        }
+      } catch {}
       // eslint-disable-next-line no-console
       console.error(`Failed to start ingest-only server: Port in use at ${base}${opts.logsRoute}`);
     }

packages/mcp/src/store.ts

@@ -51,6 +51,12 @@ export class LogStore {
     }
   }
 
+  /** Set a baseline timestamp without deleting entries. If session omitted, use global baseline. */
+  baseline(session?: string, when: number = Date.now()) {
+    const key = session || '__global__';
+    this.baselineTimestamps.set(key, when);
+  }
+
   toText(session?: string): string {
     return this.snapshot(session).map((e) => {
       const sid = (e.sessionId || 'anon').slice(0, 8);

packages/mcp/src/tools/getLogs.ts

@@ -19,7 +19,9 @@ export function registerGetLogsTool(ctx: McpToolContext) {
         limit = 1000,
         contains,
         sinceMs,
-        project
+        project,
+        autoBaseline = true,
+        stackedMode = false
       } = safeArgs as typeof GetLogsSchema['_output'];
 
       const validSession = validateSessionId(session);
@@ -109,6 +111,15 @@ export function registerGetLogsTool(ctx: McpToolContext) {
         }).join('\n');
       }
 
+      // Auto-baseline unless stackedMode
+      try {
+        if (autoBaseline && !stackedMode) {
+          // baseline per project if selected; else by session or global
+          const baselineSession = validSession;
+          store.baseline(baselineSession);
+        }
+      } catch {}
+
       return {
         content: [
           { type: 'text' as const, text }

packages/next/README.md

@@ -274,9 +274,9 @@ This package depends on [@browser-echo/core](https://github.com/instructa/browse
 ## License
 
 MIT
-
 ## Links
 
 - [Main Repository](https://github.com/instructa/browser-echo)
 - [Documentation](https://github.com/instructa/browser-echo#readme)
 - [Core Package](https://github.com/instructa/browser-echo/tree/main/packages/core)
+

packages/next/src/route.ts

@@ -10,35 +10,40 @@ 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;
+
 export async function POST(req: NextRequest) {
   let payload: Payload | null = null;
   try { payload = (await req.json()) as Payload; }
   catch { return new NextResponse('invalid JSON', { status: 400 }); }
   if (!payload || !Array.isArray(payload.entries)) return new NextResponse('invalid payload', { status: 400 });
 
-  // 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;
+  // Fixed resolution (single-server): env or default localhost:5179 (strip optional /mcp suffix)
+  const baseUrl = (process.env.BROWSER_ECHO_MCP_URL || 'http://127.0.0.1:5179').replace(/\/$/, '').replace(/\/mcp$/i, '');
+  const mcp = { url: baseUrl, routeLogs: '/__client-logs' } as const;
+  // No background probes; only flip after a successful POST
 
-  // 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,
-        body: JSON.stringify(payload),
-        keepalive: true,
-        cache: 'no-store',
-      }).catch(() => void 0);
-    } catch {}
-  }
+  // Forward to MCP server (fire-and-forget) and update connection state
+  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 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 {} });
+  } catch {}
 
-  // Dynamically decide whether to print to terminal
-  const shouldPrint = !mcp.url;
+  // Print locally until first confirmed forward; then suppress
+  const shouldPrint = !__hasForwardedOnce;
 
   const sid = (payload.sessionId ?? 'anon').slice(0, 8);
   for (const entry of payload.entries) {