neuron-inspector 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,208 @@
+# neuron-inspector
+
+**51 browser tools for AI agents.** Turn Chrome into an MCP-powered DevOps platform — inspect DOM, automate clicks, audit security, mock APIs, extract data, record demos — all from Claude Code, Cursor, Windsurf, or any MCP client.
+
+```bash
+npx neuron-inspector
+```
+
+## What this does
+
+Your AI agent can't see your browser. neuron-inspector fixes that.
+
+It bridges a Chrome extension to your AI coding tool via MCP (Model Context Protocol). Once connected, your agent gets 51 tools that let it read the DOM, click buttons, run JS, search network traffic, audit accessibility, scan for security leaks, mock API responses, extract structured data from any page, and more.
+
+No API keys. No cloud. Runs entirely on localhost.
+
+## Setup (2 minutes)
+
+### 1. Install the Chrome extension
+
+Download from [neuron.ng/extension](https://neuron.ng/extension) and sideload it:
+
+1. Extract the zip
+2. Open `chrome://extensions`, enable Developer Mode
+3. Click "Load unpacked" and select the folder
+
+### 2. Register the MCP server
+
+**Claude Code:**
+```bash
+claude mcp add neuron-inspector -- npx neuron-inspector
+```
+
+**Cursor** — add to `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "neuron-inspector": {
+      "command": "npx",
+      "args": ["neuron-inspector"]
+    }
+  }
+}
+```
+
+**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "neuron-inspector": {
+      "command": "npx",
+      "args": ["neuron-inspector"]
+    }
+  }
+}
+```
+
+That's it. The extension auto-connects to the bridge on `ws://localhost:7377`.
+
+## The 51 tools
+
+### Inspect & Debug
+| Tool | What it does |
+|------|-------------|
+| `neuron_query_dom` | DOM snapshot of the page or a subtree |
+| `neuron_find_elements` | Find elements by CSS selector or visible text |
+| `neuron_evaluate_js` | Run JavaScript in page context |
+| `neuron_get_logs` | Console logs filtered by level, tab, search |
+| `neuron_screenshot` | PNG screenshot of the visible area |
+| `neuron_diagnose` | Connection health — extension connected? Tabs open? |
+| `neuron_list_tabs` | Open tabs with platform detection |
+
+### Browse & Automate
+| Tool | What it does |
+|------|-------------|
+| `neuron_click` | Click an element by selector or text |
+| `neuron_type` | Type into inputs and contenteditable |
+| `neuron_scroll` | Scroll by pixels or scroll an element into view |
+| `neuron_navigate` | Navigate a tab to a URL |
+| `neuron_open_tab` | Open a new tab |
+| `neuron_reload` | Reload a tab |
+| `neuron_run_sequence` | Execute a multi-step sequence (click, type, wait, eval) |
+
+### Network Intelligence
+| Tool | What it does |
+|------|-------------|
+| `neuron_get_requests` | Query captured HTTP requests by tab, method, status, URL |
+| `neuron_get_errors` | Recent 4xx/5xx responses and console errors |
+| `neuron_get_ws_frames` | WebSocket and SSE frame history |
+| `neuron_export_har` | Export traffic as HAR 1.2 |
+| `neuron_search_traffic` | Full-text search across all captured response bodies |
+| `neuron_discover_apis` | Auto-map API endpoints from observed traffic |
+| `neuron_replay_request` | Re-fire an HTTP request with the browser's live session |
+| `neuron_waterfall` | Network timing breakdown — DNS, TLS, TTFB per resource |
+
+### Security Scan
+| Tool | What it does |
+|------|-------------|
+| `neuron_security_scan` | Scan for leaked secrets, missing headers, CORS issues, mixed content |
+| `neuron_check_auth` | Verify platform credentials are still valid |
+| `neuron_detect_blocker` | Detect rate limits, captchas, login walls |
+
+### Quality Audits
+| Tool | What it does |
+|------|-------------|
+| `neuron_a11y_audit` | WCAG accessibility audit — contrast, labels, headings, tabindex |
+| `neuron_perf_snapshot` | Core Web Vitals, resource breakdown, memory, long tasks |
+| `neuron_seo_audit` | Title, meta, OG, headings, structured data, link ratio |
+
+### Network Mocking
+| Tool | What it does |
+|------|-------------|
+| `neuron_set_mock` | Intercept requests and return custom responses |
+| `neuron_get_mocks` | List active mock rules |
+| `neuron_clear_mocks` | Remove all mocks |
+
+### Cookies & Storage
+| Tool | What it does |
+|------|-------------|
+| `neuron_get_cookies` | Read all cookies for a URL |
+| `neuron_set_cookie` | Set a cookie |
+| `neuron_delete_cookie` | Delete a cookie |
+| `neuron_get_storage` | Read localStorage or sessionStorage |
+| `neuron_clear_storage` | Clear storage |
+
+### Page Monitoring
+| Tool | What it does |
+|------|-------------|
+| `neuron_snapshot_state` | Capture page state (DOM, visibility, text) for later diff |
+| `neuron_diff_states` | Compare two snapshots — detect what changed |
+| `neuron_watch_element` | Watch a selector for changes over time |
+| `neuron_get_watches` | Check accumulated changes |
+| `neuron_stop_watch` | Stop watching |
+| `neuron_extract_data` | Extract structured data from repeating patterns (feeds, tables, listings) |
+
+### Demo Recording
+| Tool | What it does |
+|------|-------------|
+| `neuron_start_recording` | Record user interactions as a replayable workflow |
+| `neuron_stop_recording` | Save the recording |
+| `neuron_list_workflows` | List saved workflows |
+| `neuron_start_replay` | Replay a workflow |
+| `neuron_stop_replay` | Stop replay |
+| `neuron_start_demo` | Record a demo video with chapters, captions, cursor overlay |
+| `neuron_workflow_status` | Current engine state |
+
+### Other
+| Tool | What it does |
+|------|-------------|
+| `neuron_trigger_post` | Trigger the IG post runner |
+| `neuron_session_diagnostics` | Agent session health — capture rate, stalls, auth, buffers |
+
+## Examples
+
+**"Why is this page slow?"**
+```
+→ neuron_perf_snapshot { tabId: 123 }
+← LCP: 3.2s, CLS: 0.04, 14 render-blocking scripts, heaviest: analytics.js (890KB)
+```
+
+**"Check this page for security issues"**
+```
+→ neuron_security_scan { tabId: 123 }
+← 3 findings: API key leaked in inline script, missing CSP header, autocomplete on password field
+```
+
+**"What APIs is this SPA calling?"**
+```
+→ neuron_discover_apis {}
+← 12 endpoints: GET /api/users/{id} (called 8x), POST /api/auth/refresh (2x), ...
+```
+
+**"Extract all product listings from this page"**
+```
+→ neuron_extract_data { tabId: 123 }
+← 47 items: [{ text: "Nike Air Max", link: "/product/123", image: "...", price: "$129" }, ...]
+```
+
+**"Mock the payments API to return a 500"**
+```
+→ neuron_set_mock { urlPattern: "*/api/payments*", responseStatus: 500, responseBody: "{\"error\":\"service down\"}" }
+← Mock rule active. All matching requests will return 500.
+```
+
+## How it works
+
+```
+┌─────────────┐     WebSocket      ┌──────────────────┐     stdio/MCP     ┌──────────────┐
+│   Chrome +   │ ←──────────────→  │  neuron-inspector │ ←──────────────→ │  Claude Code  │
+│  Extension   │   localhost:7377   │    (this pkg)     │                  │  / Cursor     │
+└─────────────┘                    └──────────────────┘                   └──────────────┘
+```
+
+1. The Chrome extension captures network traffic, DOM state, and console logs in real time
+2. `neuron-inspector` runs as a local bridge — WebSocket server on port 7377 (extension connects here) + MCP server on stdio (your AI tool connects here)
+3. Your AI agent calls tools via MCP → the bridge forwards them to the extension → the extension executes in Chrome → results flow back
+
+Everything runs on localhost. No data leaves your machine.
+
+## Requirements
+
+- Node.js 18+
+- Chrome (or Chromium-based browser)
+- [Neuron extension](https://neuron.ng/extension) installed
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neuron-inspector",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server exposing Neuron extension browser state as queryable tools",
   "type": "module",
   "main": "dist/server.js",