Skip to content

Commit fcb5d7b

Browse files
regenrekregenrek
committed
feat: expand documentation for MCP server setup and integration across frameworks, including installation steps and environment variable configurations
1 parent d6322d7 commit fcb5d7b

8 files changed

Lines changed: 369 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@ No production impact. Providers enable this across frameworks by injecting a tin
1616

1717
## Quick start
1818

19+
#### 1. Install Framework Package
20+
21+
First, set up Browser Echo for your framework:
22+
1923
| Framework | Quick Setup |
2024
| --- | --- |
2125
| TanStack / Vite | [Installation Guide](packages/vite/README.md#tanstack-start) |
@@ -29,6 +33,12 @@ No production impact. Providers enable this across frameworks by injecting a tin
2933

3034
> Framework users only install their provider + `@browser-echo/core`. No cross‑framework bloat.
3135
36+
#### 2. Use Browser Echo MCP (Optional)
37+
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.
39+
40+
**📖 [Set up Browser Echo MCP Server](packages/mcp/README.md)** for AI assistant integration
41+
3242
## What you get
3343

3444
- Drop‑in client patch that wraps `console.log/info/warn/error/debug`
@@ -39,7 +49,7 @@ No production impact. Providers enable this across frameworks by injecting a tin
3949
- Works great with AI assistants reading your terminal
4050
- **NEW:** MCP (Model Context Protocol) support for enhanced AI assistant integration
4151

42-
## MCP Support for AI Assistants
52+
## Browser Echo MCP Server
4353

4454
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:
4555

@@ -57,7 +67,20 @@ This integration makes debugging with AI assistants much more powerful - they ca
5767

5868
**📖 [Full MCP Setup Guide & Documentation](packages/mcp/README.md)**
5969

60-
## Options (shared shape)
70+
### MCP discovery and forwarding (Vite / Next / Nuxt)
71+
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)
82+
83+
## Options
6184

6285
Most providers accept these options (names may appear as plugin options or component props):
6386

‎packages/core/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,12 @@ Core client-side functionality for streaming browser console logs to your dev te
44

55
This package provides the `initBrowserEcho` function that patches `console.*` methods and forwards logs to a development server endpoint. It's designed to be used as a dependency by framework-specific providers.
66

7+
## Table of Contents
8+
9+
- [Installation](#installation)
10+
- [Usage](#usage)
11+
- [Install MCP Server](#install-mcp-server)
12+
713
## Features
814

915
- Drop-in client patch that wraps `console.log/info/warn/error/debug`
@@ -65,6 +71,21 @@ This core package is typically used through framework-specific providers:
6571

6672
See the [main repository](https://github.com/instructa/browser-echo) for complete setup guides.
6773

74+
## Install MCP Server
75+
76+
For core usage, MCP forwarding depends on your server-side route implementation. The core package only handles browser-side log collection.
77+
78+
**📖 [First, set up the MCP server](../mcp/README.md#installation) for your AI assistant, then configure framework options below.**
79+
80+
### Environment Variables
81+
82+
- `BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp` — Set in your server environment
83+
- `BROWSER_ECHO_SUPPRESS_TERMINAL=1` — Control terminal output in your route handler
84+
85+
### Server Route MCP Integration
86+
87+
See the [React MCP Settings](../react/README.md#mcp-settings) for an example server route with MCP forwarding.
88+
6889
## Author
6990

7091
[Kevin Kern](https://github.com/regenrek)

‎packages/mcp/README.md‎

Lines changed: 110 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -15,53 +15,121 @@ Your AI assistant will automatically use the appropriate MCP tools to fetch and
1515

1616
---
1717

18-
## Installation for AI Assistants
18+
## Installation
1919

20-
### Cursor IDE
20+
**⚠️ PREREQUISITE:** Before setting up the MCP server, you **must first install and configure a Browser Echo framework package** (Vite, Next.js, Nuxt, etc.) in your project. The MCP server needs your framework to forward browser logs to it.
21+
22+
**📖 [Choose your framework and complete setup first](../README.md#quick-start)**
23+
24+
Once your framework is set up and forwarding logs, install the Browser Echo MCP server with your client. Using stdio transport.
25+
26+
**Standard config** works in most of the tools:
2127

22-
Add to your `.cursor/mcp.json`:
2328

2429
```json
2530
{
2631
"mcpServers": {
2732
"browser-echo": {
2833
"command": "npx",
29-
"args": ["@browser-echo/mcp"]
34+
"args": ["-y","@browser-echo/mcp"]
3035
}
3136
}
3237
}
3338
```
3439

35-
### Claude Desktop
40+
### Cursor
3641

37-
Add to your Claude Desktop MCP config:
42+
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=browser-echo&config=eyJjb21tYW5kIjoibnB4IC15IEBicm93c2VyLWVjaG8vbWNwIn0%3D)
43+
44+
<details>
45+
<summary>Manual Install</summary>
46+
47+
Add to your `.cursor/mcp.json`:
3848

3949
```json
4050
{
4151
"mcpServers": {
4252
"browser-echo": {
4353
"command": "npx",
44-
"args": ["@browser-echo/mcp"]
54+
"args": ["-y","@browser-echo/mcp"]
4555
}
4656
}
4757
}
4858
```
59+
</details>
4960

50-
---
61+
### Claude Code
62+
63+
Add to your Claude Desktop MCP config:
64+
65+
```json
66+
claude mcp add browser-echo-mcp npx -y @browser-echo/mcp
67+
```
68+
69+
70+
<details>
71+
<summary>Claude Desktop</summary>
72+
73+
Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.
74+
</details>
75+
76+
<details>
77+
<summary>Gemini CLI</summary>
78+
79+
Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use the standard config above.
80+
</details>
81+
82+
<details>
83+
<summary>opencode</summary>
84+
85+
Follow the MCP Servers [documentation](https://opencode.ai/docs/mcp-servers/). For example in `~/.config/opencode/opencode.json`:
86+
87+
```json
88+
{
89+
"$schema": "https://opencode.ai/config.json",
90+
"mcp": {
91+
"browser-echo": {
92+
"type": "local",
93+
"command": [
94+
"npx",
95+
"@browser-echo/mcp"
96+
],
97+
"enabled": true
98+
}
99+
}
100+
}
101+
102+
```
103+
</details>
51104

52-
## Streamable HTTP Setup
105+
<details>
106+
<summary>VS Code</summary>
53107

54-
If you prefer HTTP transport over stdio (useful for web-based AI tools):
108+
#### Click the button to install:
55109

56-
### 1. Install the package
110+
#### Or install manually:
111+
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:
57113

58114
```bash
59-
npm install -g @browser-echo/mcp
60-
# or
61-
pnpm add -g @browser-echo/mcp
115+
# For VS Code
116+
code --add-mcp '{"name":"browser-echo","command":"npx","args":["@browser-echo/mcp@latest"]}'
62117
```
63118

64-
### 2. Start the HTTP server
119+
After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.
120+
</details>
121+
122+
<details>
123+
<summary>Windsurf</summary>
124+
125+
Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config above.
126+
127+
</details>
128+
129+
130+
### Streamable HTTP Setup (Server usage)
131+
132+
If you prefer HTTP transport (useful for web-based AI tools):
65133

66134
```bash
67135
# Start with full HTTP transport
@@ -71,10 +139,35 @@ npx @browser-echo/mcp --http
71139
npx @browser-echo/mcp --http --host 127.0.0.1 --port 5179
72140
```
73141

74-
### 3. Configure your AI assistant
75-
76142
Point your MCP client to: `http://127.0.0.1:5179/mcp`
77143

144+
```json
145+
{
146+
"mcpServers": {
147+
"browser-echo": {
148+
"url": "http://localhost:5179/mcp"
149+
}
150+
}
151+
}
152+
```
153+
154+
---
155+
156+
## Framework Options
157+
158+
Each framework package supports MCP configuration options:
159+
160+
| Framework | Install MCP Server |
161+
| --- | --- |
162+
| TanStack / Vite | [Install MCP Server](../vite/README.md#install-mcp-server) |
163+
| Nuxt 3/4 | [Install MCP Server](../nuxt/README.md#install-mcp-server) |
164+
| Next.js (App Router) | [Install MCP Server](../next/README.md#install-mcp-server) |
165+
| Vue + Vite | [Install MCP Server](../vite/README.md#install-mcp-server) |
166+
| React + Vite | [Install MCP Server](../vite/README.md#install-mcp-server) |
167+
| Vue (non-Vite) | [Install MCP Server](../vue/README.md#install-mcp-server) |
168+
| React (non-Vite) | [Install MCP Server](../react/README.md#install-mcp-server) |
169+
| Core | [Install MCP Server](../core/README.md#install-mcp-server) |
170+
78171
---
79172

80173
## Available Tools

‎packages/next/README.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,14 @@ Next.js App Router integration for streaming browser console logs to your dev te
44

55
Since Turbopack doesn't use Vite, this package provides a tiny route handler and an early script component to patch `console.*` methods and forward logs to your development server.
66

7+
## Table of Contents
8+
9+
- [Installation](#installation)
10+
- [Quick Setup](#quick-setup-recommended)
11+
- [Manual Setup](#manual-setup)
12+
- [Available Options](#available-options)
13+
- [Install MCP Server](#install-mcp-server)
14+
715
## Features
816

917
- Next.js App Router compatible
@@ -177,6 +185,46 @@ export default function RootLayout({ children }: { children: ReactNode }) {
177185
export { POST, runtime, dynamic } from '@browser-echo/next/route';
178186
```
179187

188+
## Install MCP Server
189+
190+
Next.js automatically discovers and forwards logs to MCP servers. No configuration needed in most cases!
191+
192+
**📖 [First, set up the MCP server](../mcp/README.md#installation) for your AI assistant, then configure framework options below.**
193+
194+
### Auto-Discovery (Default)
195+
196+
The Next.js route handler automatically detects MCP servers and forwards logs when available. When MCP is detected, terminal output is suppressed by default.
197+
198+
### Environment Variables
199+
200+
- `BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp` — Set MCP server URL
201+
- `BROWSER_ECHO_SUPPRESS_TERMINAL=1` — Force suppress terminal output
202+
- `BROWSER_ECHO_SUPPRESS_TERMINAL=0` — Force show terminal output even when MCP is active
203+
204+
### Disable MCP Discovery
205+
206+
```ts
207+
// app/api/client-logs/route.ts
208+
import { POST as BasePost } from '@browser-echo/next/route';
209+
210+
// Custom handler without MCP discovery
211+
export async function POST(request: NextRequest) {
212+
// Set environment to disable MCP
213+
const originalMcpUrl = process.env.BROWSER_ECHO_MCP_URL;
214+
delete process.env.BROWSER_ECHO_MCP_URL;
215+
216+
const result = await BasePost(request);
217+
218+
// Restore original env
219+
if (originalMcpUrl) process.env.BROWSER_ECHO_MCP_URL = originalMcpUrl;
220+
221+
return result;
222+
}
223+
224+
export const runtime = 'nodejs';
225+
export const dynamic = 'force-dynamic';
226+
```
227+
180228
## How it works
181229

182230
1. `<BrowserEchoScript />` injects client-side code that patches console methods

‎packages/nuxt/README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@ Nuxt 3/4 module for streaming browser console logs to your dev terminal.
44

55
This Nuxt module registers a Nitro server route and a client plugin (dev-only) with zero manual wiring beyond adding the module to your configuration.
66

7+
## Table of Contents
8+
9+
- [Installation](#installation)
10+
- [Setup](#setup)
11+
- [Configuration Options](#configuration-options)
12+
- [Install MCP Server](#install-mcp-server)
13+
714
## Features
815

916
- Zero-config Nuxt 3/4 module
@@ -90,6 +97,38 @@ export default defineNuxtConfig({
9097
});
9198
```
9299

100+
## Install MCP Server
101+
102+
Nuxt automatically discovers and forwards logs to MCP servers. No configuration needed in most cases!
103+
104+
**📖 [First, set up the MCP server](../mcp/README.md#installation) for your AI assistant, then configure framework options below.**
105+
106+
### Auto-Discovery (Default)
107+
108+
The Nuxt server handler automatically detects MCP servers and forwards logs when available. When MCP is detected, terminal output is suppressed by default.
109+
110+
### Environment Variables
111+
112+
- `BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp` — Set MCP server URL
113+
- `BROWSER_ECHO_SUPPRESS_TERMINAL=1` — Force suppress terminal output
114+
- `BROWSER_ECHO_SUPPRESS_TERMINAL=0` — Force show terminal output even when MCP is active
115+
116+
### Disable MCP Discovery
117+
118+
```ts
119+
// nuxt.config.ts
120+
export default defineNuxtConfig({
121+
modules: ['@browser-echo/nuxt'],
122+
123+
// Disable MCP discovery via environment
124+
runtimeConfig: {
125+
browserEcho: {
126+
disableMcp: true // Custom flag to disable MCP in your handler
127+
}
128+
}
129+
});
130+
```
131+
93132
## How it works
94133

95134
1. The module registers a Nitro server route at `/__client-logs` (configurable)

0 commit comments

Comments
 (0)