slimbrowser-mcp 0.1.0

package/README.md

@@ -0,0 +1,271 @@
+<p align="center">
+  <h1 align="center">slimbrowser-mcp</h1>
+  <p align="center">A token-efficient browser MCP for AI agents. Minimal context, maximum visibility.</p>
+</p>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> &middot;
+  <a href="#one-command-bootstrap">One-command Bootstrap</a> &middot;
+  <a href="#packaging-for-distribution">Packaging</a> &middot;
+  <a href="#why-slimbrowser-mcp">Why slimbrowser-mcp</a> &middot;
+  <a href="#architecture">Architecture</a> &middot;
+  <a href="#tool-catalog">Tools</a> &middot;
+  <a href="#claude-code-integration">Claude Code</a> &middot;
+  <a href="docs/MCP_TOOL_CATALOG.md">Full Tool Reference</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/rust-1.78+-orange?logo=rust" alt="Rust 1.78+">
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License">
+  <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP Compatible">
+  <img src="https://img.shields.io/badge/browser-Chrome-yellow?logo=googlechrome" alt="Chrome">
+</p>
+
+---
+
+## Why slimbrowser-mcp
+
+Browser automation for AI agents is expensive. A single page observation can consume **15,000-30,000 tokens** with traditional tools. Over a typical multi-step workflow, that adds up fast.
+
+slimbrowser-mcp takes a different approach:
+
+| Approach | Tokens per page read | 12-step workflow |
+|---|---|---|
+| Chrome DevTools MCP | 15,000 - 30,000 | ~200K - 380K |
+| Playwright MCP | 14,000 - 19,000 | ~180K - 250K |
+| Claude in Chrome | 4,000 - 8,000 | ~80K - 120K |
+| **slimbrowser-mcp** | **1,000 - 3,000** | **~30K - 50K** |
+
+**Up to 85% fewer tokens** than Chrome DevTools MCP. Up to 56% fewer than Claude in Chrome.
+
+### How
+
+- **Compressed observations** &mdash; `browser_observe(SUMMARY)` returns only interactive elements, not the full DOM or accessibility tree
+- **Schema-based extraction** &mdash; `browser_extract` pulls exactly the data you ask for, nothing more
+- **Smart deltas** &mdash; only report what changed between actions, not the entire page state
+- **Budget tracking** &mdash; built-in token/screenshot budget per session so agents stay within limits
+
+---
+
+## Quickstart
+
+```bash
+# Clone
+git clone git@github.com:Naresh084/slimbrowse.git
+cd slimbrowse
+
+# Run diagnostics
+cargo run -p slimbrowser-mcp -- doctor
+
+# Start the MCP server
+cargo run -p slimbrowser-mcp
+```
+
+No `.env` required. Sensible defaults are built in. Use `.env` only to override (see [`.env.example`](.env.example)).
+
+---
+
+## One-command Bootstrap
+
+No manual install flow required:
+
+```bash
+./scripts/slimbrowser-mcp-bootstrap.sh doctor
+./scripts/slimbrowser-mcp-bootstrap.sh
+```
+
+This auto-installs `slimbrowser-mcp` under `~/.slimbrowser-mcp/bin` on first run, then runs it directly.
+
+`npx`-style local launcher is also available:
+
+```bash
+npx --yes /Users/naresh/Work/Personal/browser-test doctor
+```
+
+---
+
+## Packaging for Distribution
+
+Build distributable artifacts:
+
+```bash
+./scripts/package-release.sh
+```
+
+This creates platform-specific `.tar.gz` + `.zip` + checksum in `dist/`.
+
+Install from an unpacked package:
+
+```bash
+./scripts/install-from-package.sh ./slimbrowser-mcp-<version>-<target>
+```
+
+Full distribution instructions: [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md)
+Publish instructions: [docs/PUBLISH.md](docs/PUBLISH.md)
+
+---
+
+## Architecture
+
+slimbrowser-mcp is a Rust workspace with a modular crate structure:
+
+```
+slimbrowse/
+├── apps/
+│   ├── slimbrowser-mcp     # MCP server binary (stdio + HTTP)
+│   ├── slimbrowser-cli     # Standalone CLI
+│   └── slimbrowserd        # Daemon mode
+├── crates/
+│   ├── engine-chromium        # Chrome CDP adapter
+│   ├── runtime-observe        # Compressed page observations
+│   ├── runtime-extract        # Schema-based data extraction
+│   ├── runtime-actions        # Click, type, scroll, navigate
+│   ├── runtime-cost           # Token budget tracking
+│   ├── runtime-artifacts      # Screenshot & artifact storage
+│   ├── runtime-policy         # Session policy (strict/unrestricted)
+│   ├── session-manager        # Multi-session lifecycle
+│   ├── tab-graph              # Tab state management
+│   ├── mcp-server             # MCP protocol layer
+│   ├── mcp-types              # MCP type definitions
+│   ├── sdk-rust               # Rust SDK for embedding
+│   └── ...                    # 12 more internal crates
+├── configs/                   # Default MCP config (TOML)
+├── examples/                  # Smoke tests & usage scripts
+└── docs/                      # Tool catalog & resource docs
+```
+
+### Key design decisions
+
+- **Chrome-only, CDP-first** &mdash; No WebDriver. Direct Chrome DevTools Protocol for speed and reliability.
+- **Embedded auto-launch** &mdash; MCP server auto-launches Chrome on first session. Auto-stops on shutdown.
+- **Headed by default** &mdash; You see exactly what the agent sees. Switch to headless with one env var.
+- **Session capture** &mdash; Every session records a playback trace for debugging and demos.
+
+---
+
+## Tool Catalog
+
+40+ browser tools organized by category:
+
+### Session Management
+| Tool | Description |
+|---|---|
+| `browser_create_session` | Create a new browser session with profile & policy |
+| `browser_close_session` | Close session with optional feedback |
+| `browser_get_session` | Get session state |
+
+### Observation & Navigation
+| Tool | Description |
+|---|---|
+| `browser_observe` | Compressed page state (SUMMARY / REGION / FULL) |
+| `browser_navigate` | Navigate to URL |
+| `browser_scroll` | Scroll page by delta |
+| `browser_back` / `browser_forward` | History navigation |
+
+### Interaction
+| Tool | Description |
+|---|---|
+| `browser_click` | Click element by ID |
+| `browser_type` | Type text into element |
+| `browser_fill_form` | Fill multiple form fields at once |
+| `browser_select` | Select dropdown option |
+
+### Extraction & Artifacts
+| Tool | Description |
+|---|---|
+| `browser_extract` | Schema-based structured data extraction |
+| `browser_screenshot` | Capture screenshot with export options |
+| `browser_evaluate_script` | Execute JavaScript in page |
+
+### Diagnostics
+| Tool | Description |
+|---|---|
+| `browser_list_console_messages` | Read console output |
+| `browser_list_network_requests` | Inspect network traffic |
+| `browser_get_performance` | Page performance metrics |
+
+[Full tool reference &rarr;](docs/MCP_TOOL_CATALOG.md)
+
+---
+
+## Claude Code Integration
+
+Install the binary:
+
+```bash
+cargo install --path apps/slimbrowser-mcp
+```
+
+Register with Claude Code:
+
+```bash
+claude mcp add --scope local slimbrowser -- slimbrowser-mcp
+```
+
+Verify:
+
+```bash
+# Inside Claude Code, run:
+/mcp
+# Look for "slimbrowser" in the connected servers list
+```
+
+Remove:
+
+```bash
+claude mcp remove --scope local slimbrowser
+```
+
+---
+
+## Configuration
+
+slimbrowser-mcp works out of the box. Override defaults via `.env` or environment variables:
+
+```bash
+# Transport
+MCP_TRANSPORT=stdio              # stdio | http | both
+MCP_RUNTIME_MODE=embedded        # embedded | remote
+
+# Browser
+CHROME_HEADLESS=false            # true for headless mode
+CHROME_LAUNCH_ON_START=true      # auto-launch Chrome
+
+# Session capture
+MCP_ENABLE_SESSION_CAPTURE=true
+MCP_SESSION_CAPTURE_DIR=/tmp/slimbrowser-mcp-playbacks
+
+# HTTP mode (optional)
+MCP_HTTP_BIND=127.0.0.1:3100
+MCP_HTTP_ENDPOINT=/mcp
+```
+
+Config file discovery order:
+1. `--config <path>`
+2. `MCP_CONFIG=<path>`
+3. `./configs/mcp.toml`
+4. `./mcp.toml`
+5. `$HOME/.config/slimbrowser-mcp/mcp.toml`
+6. Built-in defaults + `.env`
+
+---
+
+## Development
+
+```bash
+# Check everything compiles
+cargo check --workspace
+
+# Run tests
+cargo test --workspace
+
+# Lint
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "slimbrowser-mcp",
+  "version": "0.1.0",
+  "description": "npx bootstrap launcher for slimbrowser-mcp",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "scripts/slimbrowser-mcp-bootstrap.sh",
+    "scripts/slimbrowser-mcp-npx.js"
+  ],
+  "bin": {
+    "slimbrowser-mcp": "scripts/slimbrowser-mcp-npx.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/scripts/slimbrowser-mcp-bootstrap.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+INSTALL_ROOT="${SLIMBROWSER_MCP_INSTALL_ROOT:-$HOME/.slimbrowser-mcp}"
+BIN_PATH="$INSTALL_ROOT/bin/slimbrowser-mcp"
+
+if ! command -v cargo >/dev/null 2>&1; then
+  echo "error: cargo is required for bootstrap install (https://rustup.rs)" >&2
+  exit 1
+fi
+
+if [[ ! -x "$BIN_PATH" ]]; then
+  mkdir -p "$INSTALL_ROOT"
+  echo "Installing slimbrowser-mcp to $INSTALL_ROOT ..." >&2
+  cargo install \
+    --locked \
+    --force \
+    --path "$ROOT_DIR/apps/slimbrowser-mcp" \
+    --root "$INSTALL_ROOT" >/dev/null
+fi
+
+exec "$BIN_PATH" "$@"

package/scripts/slimbrowser-mcp-npx.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const { resolve } = require("node:path");
+
+if (process.platform === "win32") {
+  console.error(
+    "slimbrowser-mcp bootstrap currently supports macOS/Linux via bash bootstrap. Use cargo install on Windows."
+  );
+  process.exit(1);
+}
+
+const scriptPath = resolve(__dirname, "slimbrowser-mcp-bootstrap.sh");
+const child = spawn("bash", [scriptPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});