Merge feat/mcp-add-stdio into pkr-tests

Author: regenrek

.browser-echo-mcp.json

@@ -0,0 +1 @@
+{"url":"http://127.0.0.1:5179","routeLogs":"/__client-logs","timestamp":1755811764407,"pid":28310}

.cursor/mcp.json

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

.github/workflows/pkg-pr-new.yml

@@ -25,7 +25,7 @@ jobs:
           cache: pnpm
 
       - name: Install dependencies
-        run: pnpm install
+        run: pnpm install:packages
 
       - name: Build package
         run: pnpm build

.gitignore

@@ -25,4 +25,5 @@ pnpm-debug.log*
 .cache/
 .env.*
 .env.local
-.env.*.local
+.env.*.local
+docs/

README.md

@@ -16,16 +16,29 @@ No production impact. Providers enable this across frameworks by injecting a tin
 
 ## Quick start
 
+#### 1. Install Framework Package
+
+First, set up Browser Echo for your framework:
+
 | Framework | Quick Setup |
 | --- | --- |
-| TanStack / Vite (React/Vue) | [Installation Guide](packages/vite/README.md) |
+| TanStack / Vite | [Installation Guide](packages/vite/README.md#tanstack-start) |
 | Nuxt 3/4 | [Installation Guide](packages/nuxt/README.md) |
 | Next.js (App Router) | [Installation Guide](packages/next/README.md) |
-| Vue | [Installation Guide](packages/vue/README.md) |
-| React | [Installation Guide](packages/react/README.md) |
+| Vue + Vite | [Installation Guide](packages/vite/README.md#vue--vite) |
+| React + Vite | [Installation Guide](packages/vite/README.md#react--vite) |
+| Vue (non-Vite) | [Installation Guide](packages/vue/README.md) |
+| React (non-Vite) | [Installation Guide](packages/react/README.md) |
+| Core | [Installation Guide](packages/core/README.md) |
 
 > Framework users only install their provider + `@browser-echo/core`. No cross‑framework bloat.
 
+#### 2. Use Browser Echo MCP (Optional)
+
+**⚠️ IMPORTANT:** You **must complete step 1** (framework setup) first before MCP will work. The MCP server needs your framework to forward browser logs to it.
+
+**📖 [Set up Browser Echo MCP Server](packages/mcp/README.md)** for AI assistant integration
+
 ## What you get
 
 - Drop‑in client patch that wraps `console.log/info/warn/error/debug`
@@ -34,8 +47,40 @@ No production impact. Providers enable this across frameworks by injecting a tin
 - Colorized terminal output
 - Optional file logging (Vite provider only)
 - Works great with AI assistants reading your terminal
+- **NEW:** MCP (Model Context Protocol) support for enhanced AI assistant integration
+
+## Browser Echo MCP Server
+
+Browser Echo includes built-in MCP (Model Context Protocol) server support, enabling AI assistants like Claude (via Cursor) to interact with your frontend logs using natural language commands:
+
+- **"Check frontend logs"** - Retrieves recent console logs
+- **"Show only errors from the last 2 minutes"** - Filters by level and time
+- **"Find hydration mismatch warnings"** - Searches for specific content
+- **"Clear logs and start fresh"** - Clears the buffer for new captures
+- **"Focus on my current tab's logs"** - Filters by session
+
+The MCP server exposes two main tools:
+- `get_logs` - Fetch logs with extensive filtering (level, session, time, content)
+- `clear_logs` - Clear logs with soft/hard modes and session-specific clearing
+
+This integration makes debugging with AI assistants much more powerful - they can directly query and analyze your frontend logs without you having to copy/paste from the terminal.
+
+**📖 [Full MCP Setup Guide & Documentation](packages/mcp/README.md)**
+
+### MCP discovery and forwarding (Vite / Next / Nuxt)
+
+- By default, when an MCP server is detected, frameworks forward logs to MCP and **suppress local terminal output**. If MCP is not found, they log locally.
+- **Vite now auto‑discovers MCP** (no need to set `mcp.url`). It resolves in this order:
+  1. Explicit option/env: Vite plugin `mcp.url` or `BROWSER_ECHO_MCP_URL`
+  2. Discovery file written by the MCP server: `.browser-echo-mcp.json` (project root or OS tmp) containing `url` and `routeLogs`
+  3. Port scan of common local ports (127.0.0.1 / localhost)
+  4. Fallback to local terminal logging
+- **Terminal output control:**
+  - `BROWSER_ECHO_SUPPRESS_TERMINAL=1` — Force suppress terminal output (even when no MCP)
+  - `BROWSER_ECHO_SUPPRESS_TERMINAL=0` — Force show terminal output (even when MCP forwarding)
+  - Framework-specific options available (see individual framework package READMEs)
 
-## Options (shared shape)
+## Options
 
 Most providers accept these options (names may appear as plugin options or component props):
 
@@ -44,7 +89,7 @@ type BrowserLogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
 
 interface BrowserEchoOptions {
   enabled?: boolean;                 // default: true (dev only)
-  route?: `/${string}`;              // default: '/__client-logs'
+  route?: `/${string}`;              // default: '/api/client-logs' (Next), '/__client-logs' (others)
   include?: BrowserLogLevel[];       // default: ['log','info','warn','error','debug']
   preserveConsole?: boolean;         // default: true (also keep logging in the browser)
   tag?: string;                      // default: '[browser]'
@@ -72,7 +117,7 @@ interface BrowserEchoOptions {
 
   * Vite: ensure plugin is added and either `index.html` exists or you import the virtual module manually.
   * Nuxt: confirm the module is in `modules[]` and you’re in dev mode.
-  * Next: make sure `app/__client-logs/route.ts` is exported and `<BrowserEchoScript />` is rendered in `<head>`.
+* Next: make sure `app/api/client-logs/route.ts` is exported and `<BrowserEchoScript />` is rendered in `<head>`.
 
 * Endpoint 404
 

example/next-app/app/api/client-logs/route.ts

@@ -1 +1,3 @@
-export { POST, runtime, dynamic } from '@browser-echo/next/route';
+import { POST as originalPOST, runtime, dynamic } from '@browser-echo/next/route';
+
+export { originalPOST as POST, runtime, dynamic };

example/next-app/package.json

@@ -9,20 +9,21 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "react": "19.1.0",
-    "react-dom": "19.1.0",
-    "next": "15.4.6"
+    "next": "15.4.7",
+    "react": "19.1.1",
+    "react-dom": "19.1.1"
   },
   "devDependencies": {
-    "typescript": "^5",
-    "@types/node": "^20",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
-    "@tailwindcss/postcss": "^4",
-    "tailwindcss": "^4",
-    "eslint": "^9",
-    "eslint-config-next": "15.4.6",
+    "@browser-echo/mcp": "workspace:*",
+    "@browser-echo/next": "https://pkg.pr.new/instructa/browser-echo/@browser-echo/next@e0bbe63",
     "@eslint/eslintrc": "^3",
-    "@browser-echo/next": "https://pkg.pr.new/instructa/browser-echo/@browser-echo/next@e0bbe63"
+    "@tailwindcss/postcss": "^4.1.12",
+    "@types/node": "^24.3.0",
+    "@types/react": "^19.1.10",
+    "@types/react-dom": "^19.1.7",
+    "eslint": "^9",
+    "eslint-config-next": "15.4.7",
+    "tailwindcss": "^4.1.12",
+    "typescript": "^5.9.2"
   }
 }

example/nuxt-app/nuxt.config.ts

@@ -5,6 +5,12 @@ export default defineNuxtConfig({
   modules: ['@browser-echo/nuxt'],
   // optional browser-echo configuration:
   browserEcho: {
-    stackMode: 'condensed'
+    stackMode: 'condensed',
+    mcpServers: {
+      browserEcho: {
+        type: 'http',
+        url: 'http://localhost:5181/mcp'
+      }
+    }
   }
 })

example/react-vite-app/README.md

@@ -15,19 +15,26 @@ Browser Echo streams browser console logs to your Vite dev server terminal with
 
 ## Getting Started
 
-1. Install dependencies:
+1. Install Browser Echo for Vite:
+   ```bash
+   npm install -D @browser-echo/vite
+   # or
+   pnpm add -D @browser-echo/vite
+   ```
+
+2. Install dependencies:
    ```bash
    npm install
    ```
 
-2. Start the development server:
+3. Start the development server:
    ```bash
    npm run dev
    ```
 
-3. Open the application in your browser and interact with the demo buttons
+4. Open the application in your browser and interact with the demo buttons
 
-4. Watch your terminal to see browser console logs streamed in real-time!
+5. Watch your terminal to see browser console logs streamed in real-time!
 
 ## What to Expect
 

example/react-vite-app/package.json

@@ -10,20 +10,20 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
   },
   "devDependencies": {
     "@browser-echo/vite": "https://pkg.pr.new/instructa/browser-echo/@browser-echo/vite@e0bbe63",
     "@eslint/js": "^9.17.0",
-    "@types/react": "^19.0.1",
-    "@types/react-dom": "^19.0.2",
-    "@vitejs/plugin-react": "^4.3.4",
+    "@types/react": "^19.1.10",
+    "@types/react-dom": "^19.1.7",
+    "@vitejs/plugin-react": "^5.0.1",
     "eslint": "^9.17.0",
     "eslint-plugin-react-hooks": "^5.0.0",
     "eslint-plugin-react-refresh": "^0.4.16",
-    "globals": "^15.14.0",
-    "typescript": "~5.7.2",
-    "vite": "^7.0.0"
+    "globals": "^16.3.0",
+    "typescript": "~5.9.2",
+    "vite": "^7.1.3"
   }
 }