localpov 0.1.1 → 0.1.2

package/README.md

@@ -1,45 +1,41 @@
 # LocalPOV
 
-Development context bridge for AI coding agents. Terminal output, browser console, network failures, Docker logs, build errors — one MCP server.
+[![npm version](https://img.shields.io/npm/v/localpov)](https://www.npmjs.com/package/localpov)
+[![npm downloads](https://img.shields.io/npm/dw/localpov)](https://www.npmjs.com/package/localpov)
+[![license](https://img.shields.io/npm/l/localpov)](https://github.com/localpov/localpov/blob/main/LICENSE)
+[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-brightgreen)](https://nodejs.org)
 
-```
-npx -y localpov --mcp
-```
-
-Your AI agent (Claude Code, Cursor, Windsurf, Claude Desktop) can now see everything happening in your dev environment — terminal errors, browser console output, failed network requests, build failures, Docker logs — without you copy-pasting anything.
-
-## Why
+Development context bridge for AI coding agents. One MCP server, 14 tools.
 
-AI coding agents are blind. They can read and write files, but they can't see:
-
-- What your terminal just printed
-- That the browser console is full of CORS errors
-- That `fetch('/api/users')` is returning 500
-- That the Docker container crashed 30 seconds ago
-- That TypeScript found 12 errors on build
+- **Terminal capture** — every shell session, auto-captured
+- **Browser console** — errors, warnings, unhandled exceptions
+- **Network failures** — 4xx/5xx responses, CORS errors, slow requests
+- **Build errors** — structured `{file, line, col, message}` from TS, ESLint, Webpack, Vite, Rust, Go
+- **Docker logs** — container output without leaving your editor
+- **Screenshots** — on-demand browser viewport capture
+- **Port scanning** — what's up, what's down
+- **System health** — memory, CPU, uptime
 
-You end up copy-pasting error messages into chat. LocalPOV fixes this — the agent reads your dev environment directly.
+Your AI agent sees everything happening in your dev environment — without you copy-pasting anything.
 
 ## Quick start
 
-```bash
-# Install globally (optional — npx works without installing)
-npm i -g localpov
-
-# Interactive setup (shell integration + MCP config)
-localpov setup
+### Claude Code
 
-# Or just start the MCP server directly
-npx -y localpov --mcp
+```bash
+claude mcp add localpov -- npx -y localpov --mcp
 ```
 
-## Setup for your AI client
+That's it. One command. Restart Claude Code and all 14 tools are available.
 
-LocalPOV works with every major AI coding tool. Pick yours:
+Shell integration is installed automatically on first run — restart your terminal to start capturing.
 
-### Claude Code
+### Claude Desktop
 
-Add to `.mcp.json` in your project root:
+Add to `claude_desktop_config.json`:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
@@ -52,14 +48,9 @@ Add to `.mcp.json` in your project root:
 }
 ```
 
-Or run `localpov mcp-config` to generate this automatically.
-
-### Claude Desktop
-
-Add to your `claude_desktop_config.json`:
+### Cursor
 
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+Add to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):
 
 ```json
 {
@@ -72,13 +63,13 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-### Cursor
+### VS Code / Copilot
 
-Add to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):
+Add to `.vscode/mcp.json` in your project root:
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "localpov": {
       "command": "npx",
       "args": ["-y", "localpov", "--mcp"]
@@ -109,7 +100,7 @@ Or configure via Windsurf UI: Cascade panel → MCPs icon → Add server.
 
 ### Any other MCP client
 
-LocalPOV uses **stdio transport** — the universal standard. Any MCP client that supports stdio works with:
+LocalPOV uses **stdio transport**. Any MCP client that supports stdio works with:
 
 ```json
 {
@@ -118,20 +109,17 @@ LocalPOV uses **stdio transport** — the universal standard. Any MCP client tha
 }
 ```
 
-### Local development (from source)
+## Why
 
-If you've cloned the repo:
+AI coding agents are blind. They can read and write files, but they can't see:
 
-```json
-{
-  "mcpServers": {
-    "localpov": {
-      "command": "node",
-      "args": ["bin/localpov-mcp.js"]
-    }
-  }
-}
-```
+- What your terminal just printed
+- That the browser console is full of CORS errors
+- That `fetch('/api/users')` is returning 500
+- That the Docker container crashed 30 seconds ago
+- That TypeScript found 12 errors on build
+
+You end up copy-pasting error messages into chat. LocalPOV fixes this — the agent reads your dev environment directly.
 
 ## What the AI agent sees
 
@@ -158,50 +146,22 @@ If you've cloned the repo:
 
 ### Terminal capture
 
-Shell integration hooks into your shell startup (`bash`, `zsh`, `fish`, `powershell`). Every terminal session's output is captured to `~/.localpov/sessions/` as plain text logs.
+Shell integration hooks into your shell startup (`bash`, `zsh`, `fish`, `powershell`). Every terminal session's output is captured to `~/.localpov/sessions/` as plain text logs. The AI agent reads these via `read_terminal` or `get_errors`.
 
-```bash
-# Install shell integration
-localpov setup
-
-# List captured sessions
-localpov sessions
+This is installed automatically when you run `npx -y localpov` for the first time.
 
-# Read a session
-localpov sessions read <pid> [lines]
+### Browser capture (optional)
 
-# Find errors across all sessions
-localpov sessions errors
+Start the proxy to capture browser console and network activity:
 
-# Remove shell integration
-localpov unsetup
+```bash
+npx -y localpov --port 3000
 ```
 
-The agent calls `read_terminal` or `get_errors` — it reads these logs directly. No copy-pasting needed.
-
-### Browser capture
-
-When the LocalPOV proxy is running, it injects a lightweight capture script into HTML responses. This gives the agent access to:
-
-- **Console output** — `console.error`, `console.warn`, unhandled exceptions, promise rejections
-- **Network requests** — failed fetches (4xx/5xx) with response bodies, slow requests, CORS errors
-- **Screenshots** — on-demand viewport capture
+Then open `http://localhost:4000` instead of `http://localhost:3000` — your app works exactly the same, but the agent can now see console errors, network failures, and take screenshots.
 
 No browser extension needed. Works in any browser.
 
-```bash
-# Start the proxy (auto-detects running dev servers)
-localpov
-
-# Or target a specific port
-localpov --port 3000
-
-# Change proxy listen port (default: 4000)
-localpov --listen 8080
-```
-
-Then open `http://localhost:4000` instead of `http://localhost:3000` — your app works exactly the same, but the agent can now see console and network activity.
-
 ### Dashboard
 
 Open `http://localhost:4000/__localpov__/` to see a visual debug panel:
@@ -244,26 +204,6 @@ Create `.localpovrc` in your project root:
 }
 ```
 
-CLI flags override config file values.
-
-## CLI reference
-
-```bash
-localpov                    # Start proxy (auto-detect dev servers)
-localpov --port 3000        # Proxy a specific port
-localpov --listen 8080      # Change proxy listen port
-localpov --mcp              # Start MCP server (stdio transport)
-localpov setup              # Interactive first-run setup
-localpov setup --shell      # Install shell integration only
-localpov unsetup            # Remove shell integration
-localpov mcp-config         # Print MCP config JSON
-localpov mcp-config cursor  # Print config for Cursor
-localpov sessions           # List captured terminal sessions
-localpov sessions read PID  # Read a session's output
-localpov sessions errors    # Find errors across sessions
-localpov doctor             # Check your setup
-```
-
 ## Supported shells
 
 | Shell | Capture method | Platforms |
@@ -273,24 +213,6 @@ localpov doctor             # Check your setup
 | fish | `script` command + fish_preexec/fish_postexec | Linux, macOS |
 | PowerShell | `Start-Transcript` + prompt function flush | Windows, Linux, macOS |
 
-## Supported frameworks
-
-Any HTTP dev server works. Framework detection is cosmetic (shown in dashboard):
-
-Next.js, Vite, Express, Angular, SvelteKit, Nuxt, Astro, Django, Flask, FastAPI, and anything else on a localhost port.
-
-## Default scanned ports
-
-`3000, 3001, 3002, 4200, 5173, 5174, 5175, 8000, 8080, 8888, 8081, 4321`
-
-Customize via `.localpovrc`:
-
-```json
-{
-  "ports": [3000, 3001, 4000, 5173, 8080, 9000]
-}
-```
-
 ## Safety
 
 - **Output capped at 50KB** per MCP response — prevents flooding the AI context

package/bin/localpov.js

@@ -395,36 +395,24 @@ async function firstRunSetup() {
 
   console.log('');
   console.log(`  ${c.b('Welcome to LocalPOV')} ${c.d(`v${pkg.version}`)}`);
-  console.log(`  ${c.d('First-time setup — takes 30 seconds')}`);
   console.log('');
 
-  // ─── Step 1: Shell integration ───
+  // ─── Step 1: Shell integration (auto) ───
   const shell = detectShell();
-  console.log(`  ${c.b('1.')} Shell integration ${c.d('(auto-capture all terminals for AI agents)')}`);
-  console.log(`     Detected: ${c.c(shell)}`);
-
-  const shellAnswer = await ask(`     Add auto-capture to ${shell} profile? [Y/n] `);
-  if (shellAnswer !== 'n' && shellAnswer !== 'no') {
-    const result = setup(shell);
-    if (result.success) {
-      if (result.already) {
-        console.log(`     ${c.g('✓')} Already installed`);
-      } else {
-        console.log(`     ${c.g('✓')} Added to ${c.d(result.profilePath)}`);
-        console.log(`     ${c.d('New terminals will be auto-captured after restart')}`);
-      }
+  const result = setup(shell);
+  if (result.success) {
+    if (result.already) {
+      console.log(`  ${c.g('✓')} Shell integration already installed ${c.d(`(${shell})`)}`);
     } else {
-      console.log(`     ${c.y('⚠')} ${result.error}`);
-      console.log(`     ${c.d('You can run `localpov setup` later to retry')}`);
+      console.log(`  ${c.g('✓')} Shell integration installed ${c.d(`(${shell} → ${result.profilePath})`)}`);
+      console.log(`  ${c.d('  Restart your terminal to start capturing sessions')}`);
     }
   } else {
-    console.log(`     ${c.d('Skipped. Run `localpov setup` anytime to enable.')}`);
+    console.log(`  ${c.y('⚠')} Shell integration: ${result.error}`);
+    console.log(`  ${c.d('  Run `localpov setup` to retry')}`);
   }
-  console.log('');
-
-  // ─── Step 2: MCP config for AI agents ───
-  console.log(`  ${c.b('2.')} AI agent integration ${c.d('(MCP server for Claude Code, Cursor, etc.)')}`);
 
+  // ─── Step 2: MCP config (auto) ───
   const mcpPath = require('path').join(process.cwd(), '.mcp.json');
   let mcpExists = false;
   try {
@@ -433,36 +421,23 @@ async function firstRunSetup() {
   } catch {}
 
   if (mcpExists) {
-    console.log(`     ${c.g('✓')} Already configured in ${c.d('.mcp.json')}`);
+    console.log(`  ${c.g('✓')} MCP config already in ${c.d('.mcp.json')}`);
   } else {
-    const mcpAnswer = await ask(`     Create .mcp.json in this project? [Y/n] `);
-    if (mcpAnswer !== 'n' && mcpAnswer !== 'no') {
-      const mcpConfig = {
-        mcpServers: {
-          localpov: {
-            command: 'npx',
-            args: ['-y', 'localpov', '--mcp'],
-          },
-        },
-      };
-      try {
-        const existing = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
-        existing.mcpServers = existing.mcpServers || {};
-        existing.mcpServers.localpov = mcpConfig.mcpServers.localpov;
-        fs.writeFileSync(mcpPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-      } catch {
-        fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf8');
-      }
-      console.log(`     ${c.g('✓')} Created ${c.d('.mcp.json')}`);
-      console.log(`     ${c.d('Restart your AI agent to activate the MCP server')}`);
-    } else {
-      console.log(`     ${c.d('Skipped. Run `localpov mcp-config` to see the config.')}`);
-    }
+    console.log(`  ${c.b('Add to .mcp.json in your project root:')}`);
+    console.log('');
+    console.log(`  ${c.c('{')}`)
+    console.log(`  ${c.c('  "mcpServers": {')}`);
+    console.log(`  ${c.c('    "localpov": {')}`);
+    console.log(`  ${c.c('      "command": "npx",')}`);
+    console.log(`  ${c.c('      "args": ["-y", "localpov", "--mcp"]')}`);
+    console.log(`  ${c.c('    }')}`);
+    console.log(`  ${c.c('  }')}`);
+    console.log(`  ${c.c('}')}`);
   }
-  console.log('');
 
+  console.log('');
   markSetupDone();
-  console.log(`  ${c.g('✓')} Setup complete. Starting LocalPOV...\n`);
+  console.log(`  ${c.g('✓')} Ready. Starting LocalPOV...\n`);
 }
 
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localpov",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Development context bridge for AI coding agents. Terminal capture, browser console, network logs, screenshots, Docker logs — one MCP server.",
   "bin": {
     "localpov": "bin/localpov.js",