neuron-inspector 0.1.1 → 0.1.2

package/README.md

@@ -1,30 +1,32 @@
 # 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.
+**51 browser tools for AI agents.** Your AI can't see your browser. This fixes that.
 
-```bash
-npx neuron-inspector
-```
+Inspect DOM, automate clicks, run JavaScript, search network traffic, audit security, check accessibility, scan SEO, mock APIs, extract structured data, record demos — all from Claude Code, Cursor, Windsurf, or any MCP client.
 
-## What this does
+No API keys. No cloud. Runs on localhost.
 
-Your AI agent can't see your browser. neuron-inspector fixes that.
+[![npm](https://img.shields.io/npm/v/neuron-inspector)](https://www.npmjs.com/package/neuron-inspector)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-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.
+```bash
+npx neuron-inspector
+```
 
-No API keys. No cloud. Runs entirely on localhost.
+---
 
-## Setup (2 minutes)
+## Get started
 
 ### 1. Install the Chrome extension
 
-Download from [neuron.ng/extension](https://neuron.ng/extension) and sideload it:
+Download from **[neuron.ng/extension](https://neuron.ng/extension)** and sideload:
 
-1. Extract the zip
-2. Open `chrome://extensions`, enable Developer Mode
-3. Click "Load unpacked" and select the folder
+1. Download and extract the zip
+2. Open `chrome://extensions` and enable **Developer Mode**
+3. Click **Load unpacked** and select the extracted folder
+4. The extension icon appears in your toolbar
 
-### 2. Register the MCP server
+### 2. Connect to your AI tool
 
 **Claude Code:**
 ```bash
@@ -55,9 +57,75 @@ claude mcp add neuron-inspector -- npx neuron-inspector
 }
 ```
 
-That's it. The extension auto-connects to the bridge on `ws://localhost:7377`.
+### 3. Use it
+
+Open any page in Chrome. Ask your AI agent to interact with it. Done.
+
+---
+
+## What you can do
+
+### Ask your agent to debug a page
+
+> "Why is this page slow?"
+
+The agent calls `neuron_perf_snapshot` and gets back Core Web Vitals, render-blocking scripts, memory usage, and the heaviest resources.
+
+> "Check this page for security issues"
+
+`neuron_security_scan` finds leaked API keys in inline scripts, missing CSP headers, mixed content, insecure forms, exposed source maps.
+
+> "Is this page accessible?"
+
+`neuron_a11y_audit` runs a WCAG audit — color contrast failures, missing alt text, broken heading hierarchy, unlabeled form fields.
+
+### Ask your agent to explore traffic
+
+> "What APIs is this SPA calling?"
+
+`neuron_discover_apis` maps every endpoint from observed traffic — call counts, status codes, auth patterns, response shapes.
+
+> "Search all network responses for 'user_id'"
+
+`neuron_search_traffic` does full-text search across every captured response body.
+
+> "Show me the network waterfall"
+
+`neuron_waterfall` gives DNS, TCP, TLS, TTFB timing per resource — the same view as DevTools Network, but in your agent's context.
+
+### Ask your agent to interact with the page
+
+> "Click the Sign Up button"
+
+`neuron_click` finds it by CSS selector or visible text and clicks it.
+
+> "Fill in the email field with test@example.com"
+
+`neuron_type` targets the input and types into it.
+
+> "Scroll down and extract all the product listings"
+
+`neuron_scroll` + `neuron_extract_data` — scrolls the page and pulls structured data from repeating patterns (cards, tables, feeds).
+
+### Ask your agent to test edge cases
 
-## The 51 tools
+> "Mock the payments API to return a 500 error"
+
+`neuron_set_mock` intercepts matching requests and returns your custom response. Test error states without touching the real backend.
+
+> "Take a snapshot, click submit, then tell me what changed"
+
+`neuron_snapshot_state` before, action, `neuron_diff_states` after — detects DOM changes, added/removed elements, URL changes.
+
+### Ask your agent to record and replay
+
+> "Record what I'm doing as a workflow"
+
+`neuron_start_recording` captures clicks, typing, and navigation. `neuron_start_demo` replays it as a polished video with chapter markers and cursor overlay.
+
+---
+
+## All 51 tools
 
 ### Inspect & Debug
 | Tool | What it does |
@@ -67,141 +135,101 @@ That's it. The extension auto-connects to the bridge on `ws://localhost:7377`.
 | `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_diagnose` | Connection health check |
 | `neuron_list_tabs` | Open tabs with platform detection |
 
 ### Browse & Automate
 | Tool | What it does |
 |------|-------------|
-| `neuron_click` | Click an element by selector or text |
+| `neuron_click` | Click 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_scroll` | Scroll by pixels or into view |
+| `neuron_navigate` | Navigate 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) |
+| `neuron_run_sequence` | Multi-step automation (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_requests` | Query HTTP requests by tab, method, status, URL |
+| `neuron_get_errors` | Recent 4xx/5xx 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 |
+| `neuron_export_har` | Export as HAR 1.2 |
+| `neuron_search_traffic` | Full-text search across response bodies |
+| `neuron_discover_apis` | Auto-map API endpoints from traffic |
+| `neuron_replay_request` | Re-fire a request with the browser's live session |
+| `neuron_waterfall` | DNS/TLS/TTFB timing per resource |
 
-### Security Scan
+### Security
 | 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_security_scan` | Leaked secrets, missing headers, CORS, mixed content |
+| `neuron_check_auth` | Verify platform credentials |
 | `neuron_detect_blocker` | Detect rate limits, captchas, login walls |
 
-### Quality Audits
+### Quality
 | 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 |
+| `neuron_a11y_audit` | WCAG audit — contrast, labels, headings, tabindex |
+| `neuron_perf_snapshot` | Core Web Vitals, resource breakdown, memory |
+| `neuron_seo_audit` | Meta, OG, headings, structured data, links |
 
 ### Network Mocking
 | Tool | What it does |
 |------|-------------|
-| `neuron_set_mock` | Intercept requests and return custom responses |
+| `neuron_set_mock` | Intercept requests, 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_get_cookies` | Read cookies for a URL |
 | `neuron_set_cookie` | Set a cookie |
 | `neuron_delete_cookie` | Delete a cookie |
-| `neuron_get_storage` | Read localStorage or sessionStorage |
+| `neuron_get_storage` | Read localStorage / 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_snapshot_state` | Capture page state for later diff |
+| `neuron_diff_states` | Compare two snapshots |
+| `neuron_watch_element` | Watch a selector for changes |
 | `neuron_get_watches` | Check accumulated changes |
 | `neuron_stop_watch` | Stop watching |
-| `neuron_extract_data` | Extract structured data from repeating patterns (feeds, tables, listings) |
+| `neuron_extract_data` | Extract structured data from feeds, tables, listings |
 
 ### Demo Recording
 | Tool | What it does |
 |------|-------------|
-| `neuron_start_recording` | Record user interactions as a replayable workflow |
+| `neuron_start_recording` | Record interactions as a 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 |
+| `neuron_start_demo` | Record a demo video with chapters + cursor |
+| `neuron_workflow_status` | 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 |
+| `neuron_trigger_post` | Trigger the post runner |
+| `neuron_session_diagnostics` | Agent session health |
 
-## 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
+- Chrome or any Chromium browser
+- [Neuron extension](https://neuron.ng/extension)
+
+## Links
+
+- **Extension download:** [neuron.ng/extension](https://neuron.ng/extension)
+- **npm:** [npmjs.com/package/neuron-inspector](https://www.npmjs.com/package/neuron-inspector)
 
 ## License
 

package/dist/server.js

@@ -38,7 +38,7 @@ console.error(`[bridge] WebSocket server listening on 127.0.0.1:${PORT}`);
 // ── MCP server (Claude Code / Cursor connects via stdio) ────
 const mcp = new McpServer({
     name: "neuron-inspector",
-    version: "0.1.0",
+    version: "0.1.2",
 });
 // Register all tools
 for (const tool of TOOLS) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "neuron-inspector",
-  "version": "0.1.1",
-  "description": "MCP server exposing Neuron extension browser state as queryable tools",
+  "version": "0.1.2",
+  "description": "51 browser tools for AI agents. Turn Chrome into an MCP server — inspect DOM, automate clicks, audit security, mock APIs, extract data, record demos.",
   "type": "module",
   "main": "dist/server.js",
   "bin": {
@@ -21,16 +21,29 @@
   "homepage": "https://neuron.ng/extension",
   "repository": {
     "type": "git",
-    "url": "https://github.com/conquext/neuron.git",
-    "directory": "packages/extension/bridge"
+    "url": "https://github.com/conquext/neuron-inspector.git"
   },
   "keywords": [
     "neuron",
     "mcp",
+    "mcp-server",
+    "model-context-protocol",
     "chrome-extension",
     "browser-tools",
+    "browser-automation",
     "inspector",
-    "devtools"
+    "devtools",
+    "ai-agents",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "dom-inspector",
+    "security-audit",
+    "accessibility",
+    "seo-audit",
+    "network-mocking",
+    "web-scraping",
+    "browser-devtools"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",