feat: add Zod validation and enhance MCP server functionality with new log retrieval and clearing tools

Author: regenrek

README.md

@@ -37,6 +37,23 @@ 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
+
+## MCP Support for AI Assistants
+
+Browser Echo now includes built-in MCP 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.
 
 ## Options (shared shape)
 

docs.md

@@ -0,0 +1,257 @@
+You’re right to push on this. **Typing `browser-echo://logs` shouldn’t be required** for beginners. Two things are true at once:
+
+1. Most MCP hosts *can* call your resource automatically from plain English (they read your resource & tool **names/descriptions** and decide what to invoke).
+2. In practice, **discoverability improves a lot** if you give the model a small, NL‑friendly *tool alias* and a couple of “quick actions” (prompts).
+
+Below is a practical plan so “check frontend logs” *just works* in Cursor and Claude—**no URIs required**—while still keeping your “fewer tools” philosophy.
+
+---
+
+## The fix: a *hybrid* interface (Resource + one NL tool + optional prompts)
+
+### 1) Keep the resource
+
+* It’s perfect for streaming/reading the whole buffer and for structured returns.
+* Keep `browser-echo://logs` and (optionally) `browser-echo://logs/{session}`.
+
+### 2) Add **one** tool alias: `get_logs`
+
+* Purpose: make intent resolution trivial. The LLM sees a tool literally named “get logs” with a description like “Fetch recent **frontend browser console logs** (errors/warnings/info) from the running dev app.”
+* Inputs (all optional):
+
+  ```ts
+  {
+    level?: ('error'|'warn'|'info'|'log'|'debug')[]; // default: all
+    session?: string;        // 8-char id prefix
+    includeStack?: boolean;  // default: true
+    limit?: number;          // e.g., 200
+    contains?: string;       // substring filter
+    sinceMs?: number;        // e.g., Date.now()-300000
+  }
+  ```
+* Output: **both** a text summary *and* a JSON list of entries (models love JSON for follow-up reasoning).
+
+> Why one tool? It acts as the **NLP entry point**. The planner can easily decide: “User said ‘check error logs’ → call `get_logs` with `level:['error','warn']`.” You still have just **two tools total** (`get_logs`, `clear_logs`).
+
+### 3) (Optional) Register **prompt templates** (“Quick actions”)
+
+* “Check frontend logs (last 2 minutes)”
+* “Check only errors & warnings”
+* “Clear and capture new logs for 30s”
+* Many hosts surface these as clickable actions or as suggestions when users type.
+
+*(If your SDK version exposes a `registerPrompt` API, use it. If not, you still get most of the win from the `get_logs` tool naming/description.)*
+
+### 4) Tune **names & descriptions** (this matters a lot)
+
+* Server name: **“Browser Echo (Frontend Logs)”**
+* Resource title: **“Frontend Browser Console Logs”**
+* Resource description: include keywords beginners use: *frontend logs, console errors, warnings, React/Next hydration, network failures*.
+* Tool description: repeat those keywords and examples (e.g., “show hydration errors, network failures, React warnings”).
+
+### 5) Return **JSON alongside text**
+
+* When resolving the resource and the tool, include **two contents**: a human‑readable plain text block (like your terminal format) **and** a JSON array of entries.
+* This lets the model filter/sort programmatically without fighting text parsing.
+
+---
+
+## What this changes in the user experience
+
+* In **Cursor** or **Claude Code**, users can simply write:
+
+  * “**Check frontend logs**”
+  * “**Show only errors from the last 2 minutes**”
+  * “**Find hydration mismatch warnings**”
+* The IDE’s planner will typically call **`get_logs`** with sensible args. If it doesn’t, the descriptive names make it very likely on the second try.
+* Power users can still say “fetch the logs resource” or click a quick action.
+
+---
+
+## Minimal code sketch (drop‑in to your server snippet)
+
+Add the `get_logs` tool *next to* your existing `clear_logs` registration:
+
+```ts
+server.registerTool(
+  'get_logs',
+  {
+    title: 'Get Frontend Browser Logs',
+    description:
+      'Fetch recent frontend browser console logs (errors/warnings/info). ' +
+      'Use this when the user asks to check frontend logs, errors, hydration issues, or network failures.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        level: {
+          type: 'array',
+          items: { enum: ['log','info','warn','error','debug'] },
+          description: 'Filter by levels'
+        },
+        session: { type: 'string', description: '8-char session id prefix' },
+        includeStack: { type: 'boolean', default: true },
+        limit: { type: 'number', minimum: 1, maximum: 5000 },
+        contains: { type: 'string', description: 'Substring filter' },
+        sinceMs: { type: 'number', description: 'Only entries with time >= sinceMs' }
+      },
+      additionalProperties: false
+    } as any
+  },
+  async ({ level, session, includeStack = true, limit = 1000, contains, sinceMs }) => {
+    let items = STORE.snapshot();
+    if (sinceMs) items = items.filter(e => !e.time || e.time >= sinceMs);
+    if (session) items = items.filter(e => (e.sessionId||'').slice(0,8) === session.slice(0,8));
+    if (level?.length) items = items.filter(e => level.includes(e.level));
+    if (contains) items = items.filter(e => (e.text||'').includes(contains));
+    if (!includeStack) items = items.map(e => ({ ...e, stack: '' }));
+    if (limit && items.length > limit) items = items.slice(-limit);
+
+    // Text view (like terminal but no ANSI)
+    const text = items.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}`;
+      }
+      return line;
+    }).join('\n');
+
+    return {
+      content: [
+        { type: 'text', text },
+        { type: 'json', json: { entries: items } }
+      ]
+    };
+  }
+);
+```
+
+> That’s it: one tool. Keep your existing resource; now beginners never need to type its URI.
+
+*(If you want “quick actions”, add prompt registrations that internally call `get_logs` with common defaults. If your SDK version doesn’t expose prompts, you can simulate by adding small, well‑named tools like `get_error_logs` that just call `get_logs` internally with `level:['error','warn']`. Still a tiny tool count.)*
+
+---
+
+## Real‑world flows that become “NLP‑easy”
+
+* “**Check frontend logs**” → calls `get_logs()` with defaults → shows text + JSON, model summarizes.
+* “**Only errors since I refreshed**” → `get_logs({ level:['error','warn'], sinceMs: <timestamp of refresh> })`
+* “**Hydration issues**” → `get_logs({ contains:'Hydration', level:['error','warn'] })`
+* “**Focus my current tab**” → model lists sessions then calls `get_logs({ session:'a1b2c3d4' })`
+* “**Start a clean capture, then I’ll repro**” → `clear_logs()` → wait → `get_logs({ level:['error','warn'] })`
+
+---
+
+## Do you *have* to keep the resource?
+
+No, but I recommend it:
+
+* Tools improve **intent mapping**.
+* Resources are great for **streaming and bulk reads** and are a natural fit for “log feed”.
+* Together, they maximize compatibility and robustness across hosts.
+
+---
+
+### Bottom line
+
+You didn’t misunderstand—**URIs are optional** in day‑to‑day use. Make it NLP‑easy by adding **one** `get_logs` tool (plus good naming/descriptions, optional quick prompts). Keep the resource as the high‑throughput backbone. That strikes the balance between **beginner‑friendly UX** and **minimal surface area**, while staying aligned with “fewer tools” best practices.
+
+
+what about clear_logs. should we keep this or not?
+
+**Keep `clear_logs`.**
+It’s one of the few side‑effect tools that’s *worth having* even under a “fewer tools” philosophy. It makes “fresh capture → reproduce → analyze” dead‑simple for the model and for beginners—no parameters, no URIs—just *“clear the logs, I’ll repro, then check errors.”*
+
+Below is the why, when, and how—plus a safe refinement you can add (optional) without increasing tool count.
+
+---
+
+## Why keep it?
+
+* **Deterministic captures:** Guarantees the next fetch contains *only* the logs from your repro, avoiding stale noise. This is hard to get right if you rely solely on “since time” filters—the planner may forget to pass them.
+* **Shorter, cleaner context:** Fewer irrelevant lines → cheaper + more accurate reasoning/summarization.
+* **Beginner‑friendly NLP:** Users can say *“start a clean capture”* and the assistant calls a single, obvious tool with no arguments.
+* **Side‑effect separation:** Getting data (resource / `get_logs`) vs. performing an action (`clear_logs`) are cleanly distinguished for the agent.
+
+You’ll still have just **two** tools total:
+
+1. `get_logs` (NLP entry point for fetching)
+2. `clear_logs` (fresh capture)
+
+That’s minimal, and it maps perfectly to how people actually debug.
+
+---
+
+## When to use it (practical patterns)
+
+* **Repro loop:**
+  *“Run `clear_logs`. I’ll trigger the bug. In 30s, fetch logs and summarize only errors/warnings with the top stack + source.”*
+* **Fix verification:**
+  *“Clear logs, reload, then confirm the previous hydration error is gone; if anything new appears, list it.”*
+* **Race conditions / intermittent failures:**
+  *“Clear logs, I’ll click around for 60s. Then group errors by stack top and propose a guard.”*
+* **Per‑session focus:**
+  *“Clear logs for my session `ab12cd34`, I’ll repro on that tab, then fetch only that session’s logs.”* (see refinement below)
+
+---
+
+## What if we removed it?
+
+You *can* approximate with `get_logs({ sinceMs })`, but:
+
+* The assistant might omit or mis‑set `sinceMs`.
+* Other background logs (extensions, other tabs) can still creep in.
+* New users don’t know to ask for a time‑window; “clear and check” is intuitive.
+
+In practice, **`clear_logs` saves mistakes** and reduces friction.
+
+---
+
+## Recommended refinement (optional, still one tool)
+
+Keep the same tool name, but give it **gentle scoping** so it’s safer and more flexible **without** adding tools:
+
+**Inputs (optional):**
+
+* `session?: string` — clear only one 8‑char session (good for multi‑tab/dev setups)
+* `scope?: 'soft' | 'hard'` — default `'soft'`
+
+**Semantics:**
+
+* **soft** (default): Don’t destroy history; just set a **baseline marker** so subsequent reads only return entries *after* the clear.
+
+  * Pros: O(1), reversible for auditing (file logging remains intact), less risky if multiple clients are connected.
+* **hard**: Drop in‑memory entries (today’s behavior).
+
+  * Pros: truly empties the ring buffer;
+  * Cons: destructive for everyone until new logs arrive.
+
+> You can implement *soft clear* by storing a per‑server (or per‑session) `baselineTimestamp`/generation and filtering on read; file logging stays untouched either way.
+
+**Example prompt that takes advantage of it:**
+
+> “Clear logs (soft) only for session `ab12cd34`. I’ll repro now. In 20 seconds, fetch logs for that session and summarize errors with source and top stack frame.”
+
+---
+
+## Defaults & UX guidance
+
+* **Keep `clear_logs` in v1** exactly as you have it (global hard clear).
+  Add the optional `session` + `scope` later; it’s backwards‑compatible.
+* Encourage assistants to use:
+
+  1. `clear_logs` →
+  2. user reproduces →
+  3. `get_logs({ level:['error','warn'] })` or plain “check frontend logs”.
+* Make sure your **resource/tool descriptions** contain NL keywords (“frontend logs”, “console errors”, “hydration”, “network failures”), so planners map user intent correctly.
+* **Don’t** let `clear_logs` touch file logs—keep it in‑memory only. The file log (if enabled) is your ground truth trail.
+
+---
+
+### TL;DR
+
+Yes—**keep `clear_logs`**. It’s the single, beginner‑friendly action that makes fresh, noise‑free captures trivial and reliable. Pair it with `get_logs` as the NLP fetch tool and you’ve got a minimal, powerful, and natural workflow. If you want extra polish, add optional `{ session, scope: 'soft' | 'hard' }`—still one tool, but safer and even more useful.