You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
chore: update README and package documentation to reflect changes in Browser Echo MCP setup, enhance configuration tips, and clarify logging options for improved user experience
`browser-echo` makes it easy for you (and your AI coding assistant) to read client-side logs directly in the server terminal during development.
5
+
`browser-echo` makes it easy for you to read client-side logs directly in your coding agent during development.
8
6
9
7
## Features
10
8
11
9
🤖 **AI Coding Assistant Support** - Perfect for Cursor AI, Claude Code, GitHub Copilot CLI, Gemini CLI, and other code editors that read terminal output
> Framework users only install their provider + `@browser-echo/core`. No cross‑framework bloat.
35
-
36
-
#### 2. Use Browser Echo MCP (Optional)
31
+
#### 2. Use Browser Echo MCP
37
32
38
-
**⚠️ 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.
33
+
**⚠️ IMPORTANT:** You **must complete step 1** (framework setup) first before MCP will work. The MCP server needs your frameworks server to forward browser logs to it.
39
34
40
35
**📖 [Set up Browser Echo MCP Server](packages/mcp/README.md)** for AI assistant integration
41
36
42
-
## What you get
37
+
## Browser Echo Core (Terminal only)
38
+
39
+
40
+
41
+
Stream browser `console.*` logs to your dev terminal and optional file logging.
42
+
43
+
`browser-echo` makes it easy for you (and your AI coding assistant) to read client-side logs directly in the server terminal during development.
44
+
45
+
> 💡 **Tip**: The MCP server isn't required for most use cases. AI assistants are usually smart enough to read CLI output directly, and the terminal solution is often faster and cheaper than MCP integration. The MCP was designed to avoid polluting the context window, but in most cases the terminal output is sufficient.
46
+
43
47
44
48
- Drop‑in client patch that wraps `console.log/info/warn/error/debug`
45
49
- Batched posts (uses `sendBeacon` when possible)
46
50
- Source hints `(file:line:col)` + stack traces
47
51
- Colorized terminal output
48
52
- Optional file logging (Vite provider only)
49
53
- Works great with AI assistants reading your terminal
50
-
-**NEW:** MCP (Model Context Protocol) support for enhanced AI assistant integration
51
54
52
-
## Browser Echo MCP Server
55
+
## Production
53
56
54
-
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:
57
+
No production impact. Providers enable this across frameworks by injecting a tiny client patch and exposing a dev-only HTTP endpoint.
-**"Show only errors from the last 2 minutes"** - Filters by level and time
58
-
-**"Find hydration mismatch warnings"** - Searches for specific content
59
-
-**"Clear logs and start fresh"** - Clears the buffer for new captures
60
-
-**"Focus on my current tab's logs"** - Filters by session
59
+
* Providers apply only in development and inject nothing into your production client bundles.
60
+
* If you also want to strip `console.*` in prod builds, use your bundler’s strip tools (e.g. Rollup plugin) separately.
61
61
62
-
The MCP server exposes two main tools:
63
-
-`get_logs` - Fetch logs with extensive filtering (level, session, time, content)
64
-
-`clear_logs` - Clear logs with soft/hard modes and session-specific clearing
62
+
## FAQ / Troubleshooting
65
63
66
-
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.
1.**Make sure you have installed framework support** → See [Install Framework Package](#1-install-framework-package) above
68
+
2.**Ensure your development server is running** before starting the MCP server
69
+
3.**Restart the MCP server** if logs still don't appear:
70
+
-**In Cursor:** Settings → MCP & Integrations → toggle "browser-echo" off and on
71
+
-**In Claude Code:** Type `/mcp` → Choose "browser-echo" → Enter → Hit `2` to reconnect
69
72
70
-
### MCP discovery and forwarding (Vite / Next / Nuxt)
73
+
</details>
71
74
72
-
- 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.
73
-
-**Vite now auto‑discovers MCP** (no need to set `mcp.url`). It resolves in this order:
74
-
1. Explicit option/env: Vite plugin `mcp.url` or `BROWSER_ECHO_MCP_URL`
75
-
2. Discovery file written by the MCP server: `.browser-echo-mcp.json` (project root or OS tmp) containing `url` and `routeLogs`
76
-
3. Port scan of common local ports (127.0.0.1 / localhost)
77
-
4. Fallback to local terminal logging
78
-
-**Terminal output control:**
79
-
-`BROWSER_ECHO_SUPPRESS_TERMINAL=1` — Force suppress terminal output (even when no MCP)
80
-
-`BROWSER_ECHO_SUPPRESS_TERMINAL=0` — Force show terminal output (even when MCP forwarding)
81
-
- Framework-specific options available (see individual framework package READMEs)
* Using a custom `base` or proxy? Keep the route same‑origin and not behind auth
88
+
* Nuxt sometimes proxies dev servers; our module registers a Nitro route directly
106
89
107
-
> Note: File logging and `truncate` are currently implemented in the Vite plugin’s dev server middleware. Nuxt/Next providers print to stdout by default (you can extend them if you need file output there).
90
+
</details>
108
91
109
-
## Production
92
+
<details>
93
+
<summary>Too many/noisy logs</summary>
110
94
111
-
* Providers apply only in development and inject nothing into your production client bundles.
112
-
* If you also want to strip `console.*` in prod builds, use your bundler’s strip tools (e.g. Rollup plugin) separately.
95
+
* Limit to `['warn','error']` and use `stackMode: 'condensed'`
96
+
97
+
</details>
98
+
99
+
<details>
100
+
<summary>Seeing duplicate logs in browser</summary>
101
+
102
+
* Set `preserveConsole: false` in your configuration
103
+
104
+
</details>
113
105
114
-
## Troubleshooting
106
+
<details>
107
+
<summary>I see logs from other running projects (multiple client setup)</summary>
115
108
116
-
* No logs appear
109
+
If you're running multiple MCP servers in different projects and seeing logs from unrelated projects, ensure each project has its own `.browser-echo-mcp.json` file in its root directory:
117
110
118
-
* Vite: ensure plugin is added and either `index.html` exists or you import the virtual module manually.
119
-
* Nuxt: confirm the module is in `modules[]` and you’re in dev mode.
120
-
* Next: make sure `app/api/client-logs/route.ts` is exported and `<BrowserEchoScript />` is rendered in `<head>`.
111
+
1.**Check for ancestor config files**: Look for `.browser-echo-mcp.json` files in parent directories (e.g., `~/projects/.browser-echo-mcp.json`). If found, delete them or move them to specific project roots.
121
112
122
-
* Endpoint 404
113
+
2.**Use distinct ports**: Start each MCP server with a unique port:
114
+
```bash
115
+
# In project A
116
+
browser-echo-mcp --port 5179
123
117
124
-
* Using a custom `base` or proxy? Keep the route same‑origin and not behind auth.
125
-
* Nuxt sometimes proxies dev servers; our module registers a Nitro route directly.
118
+
# In project B
119
+
browser-echo-mcp --port 5180
120
+
```
126
121
127
-
* Too noisy
122
+
3.**Verify project isolation**: Ensure each MCP server was started from within its own project directory (not from a shared parent).
128
123
129
-
* Limit to `['warn','error']` and use `stackMode: 'condensed'`.
124
+
4.**Check process CWD**: If using IDE integrations or task runners, make sure each MCP server process has its `CWD` set to the individual project root.
130
125
131
-
* Duplicate logs in browser
126
+
If the issue persists after following these steps, please [open an issue on GitHub](https://github.com/regenrek/vite-browser-logs/issues) with details about your setup.
> Note: File logging and `truncate` are currently implemented in the Vite plugin's dev server middleware. Nuxt/Next providers print to stdout by default (you can extend them if you need file output there).
74
+
75
+
62
76
## Framework Providers
63
77
64
78
This core package is typically used through framework-specific providers:
MCP (Model Context Protocol) server for Browser Echo — enables AI assistants to directly access and analyze your frontend browser console logs using natural language commands.
4
6
5
7
## Example Usage
@@ -21,6 +23,8 @@ Your AI assistant will automatically use the appropriate MCP tools to fetch and
21
23
22
24
**📖 [Choose your framework and complete setup first](../README.md#quick-start)**
23
25
26
+
> **💡 Configuration Tip:** Set `BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp` in your framework environment to explicitly configure MCP forwarding. See [Environment Variables](#environment-variables) for full configuration options.
27
+
24
28
Once your framework is set up and forwarding logs, install the Browser Echo MCP server with your client. Using stdio transport.
25
29
26
30
**Standard config** works in most of the tools:
@@ -39,7 +43,7 @@ Once your framework is set up and forwarding logs, install the Browser Echo MCP
@@ -109,14 +113,14 @@ Follow the MCP Servers [documentation](https://opencode.ai/docs/mcp-servers/). F
109
113
110
114
#### Or install manually:
111
115
112
-
Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the Playwright MCP server using the VS Code CLI:
116
+
Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the Browser Echo MCP server using the VS Code CLI:
0 commit comments