Metadata-Version: 2.5
Name: live-devtools-inspector-mcp
Version: 0.1.0
Summary: A local MCP server for live Chrome DevTools diagnostics.
Requires-Python: >=3.11
Requires-Dist: fastmcp==4.0.5
Requires-Dist: pydantic==2.13.4
Requires-Dist: websockets==15.0.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio==1.4.1; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Description-Content-Type: text/markdown

# Live DevTools Inspector MCP

A local FastMCP server that connects to one explicitly selected Chrome page over CDP and collects bounded, deduplicated Console, runtime-exception, and Network findings. It also provides an opt-in exact-snippet patch flow with approval, SHA-256 checks, a recovery point, fixed pytest execution, and guarded rollback.

## Install and Run

Requires Python 3.11 or newer. The dependency versions below are pinned and the FastMCP API was verified against FastMCP 4.0.5.

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m devtools_inspector.server
```

The server uses MCP stdio transport. Do not write ordinary log messages to stdout while connected to an MCP client.

## Chrome Setup

Use a dedicated browser profile. A debugging endpoint grants powerful access to every page and session in that profile; keep it bound to loopback and do not expose or forward the port.

```powershell
& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-address=127.0.0.1 `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:TEMP\devtools-inspector-chrome"
```

Open the application in that Chrome instance. Use `list_browser_targets` with `http://127.0.0.1:9222`, then pass the chosen `target_id` to `connect_browser`. Only local unauthenticated HTTP debugging endpoints and page WebSockets on that endpoint are accepted.

## VS Code Copilot MCP

Add the following to `.vscode/mcp.json` after installing the package in the project environment. Adjust `python` to the interpreter path used by this workspace if it is not on `PATH`.

```json
{
  "servers": {
    "live-devtools-inspector": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "devtools_inspector.server"],
      "env": {
        "DEVTOOLS_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

## Tools in This Slice

Browser tools: `list_browser_targets`, `connect_browser`, `select_browser_target`, `disconnect_browser`, `get_connection_status`, and live inspection start/stop/status tools.

Diagnostics: `get_live_diagnostics`, `inspect_console`, and `inspect_network`. Console/runtime issues and HTTP/network failures include source or request evidence where available. Query-string credentials and common secret patterns are redacted; request/response bodies and headers are not collected.

Fixing: `propose_fix` requires a project-relative source path, its current SHA-256, and one unique old/new snippet. `apply_patch` requires `approved=true`, stores a recovery point under `.devtools_mcp/rollback`, and appends actions to `.devtools_mcp/history.jsonl`. `run_project_checks` executes only `python -m pytest -q`; when linked to a patch, a failed or unavailable check attempts a guarded rollback. `rollback_patch` refuses to overwrite subsequent edits. A successful pytest run does not prove a browser issue is fixed; browser reinspection remains necessary.

Run the deterministic fixture app in a separate terminal with `python sample_app/server.py`, open `http://127.0.0.1:8000` in the debug Chrome profile, and connect to that page. It intentionally produces a runtime exception, a 404 API request, a broken button, and a 350 ms main-thread task.

## Tests and Limitations

Run `pytest -q`. Tests exercise normalization, redaction, loopback restrictions, patch approval, stale-file protection, and rollback without requiring Chrome.

This initial slice does not yet implement DOM/accessibility inspection, source-map resolution, performance/memory/storage/security panels, backend logs, AI diagnosis, browser automation for fix verification, reconnection, or continuous sampling beyond event-driven Console/Network capture. It does not claim a complete bug or security audit. CDP behavior should be integration-tested against supported local Chrome versions before production use.