fennec

What is Fennec?

Fennec is an MCP (Model Context Protocol) server that bridges the gap between AI agents and your development environment. Instead of you copy-pasting errors between terminal, browser, and AI, Fennec gives your AI agent direct access to all three simultaneously — and lets it run and supervise your apps, not just observe them.

The Problem It Solves

When a developer asks an AI agent "why is my login broken?", the agent is essentially blind:

What agent sees:          What developer sees:
─────────────────         ──────────────────────────────────
"I can't access           Browser Console:
  your terminal"             ✗ TypeError: jwt.sign is undefined

"Please paste the         Terminal:
  error message"             ✗ Error: JWT_SECRET not set in env

"I don't have            Network Tab:
  browser access"            ✗ POST /api/login -> 500

The developer ends up being a copy-paste bridge between their tools and the AI. Fennec eliminates this bottleneck.

With Fennec

Bug appears
    → AI checks browser console + network + server log simultaneously
    → AI correlates: "Server missing JWT_SECRET, set it in .env"
    → Fix. Done.

Related MCP server: harness-fe

Key Features

🌐 Full Cross-Browser Support

Fennec supports Chromium, Firefox, and WebKit — not just Chromium like many tools. Configure via:

{ "browser": { "type": "firefox" | "webkit" | "chromium" } }

Or environment variable: FENNEC_BROWSER_TYPE=firefox

🏆 Full-Stack Correlation (Proven)

Fennec's signature feature correlates browser errors with server logs to identify root causes automatically. The correlation engine has been tested with 7 integration scenarios covering real-world patterns:

✅ The confidence scores above are derived from actual inference rules with unit-tested pattern matching, not fabricated illustrations.

🖥️ Process & App Management — the AI-Native Control Plane

This is what makes Fennec more than an observer. Your AI agent can run, supervise, and recover your apps exactly like a senior engineer would — without you pasting logs or running commands by hand:

• start / run — launch any app as a detached, supervised daemon. Logs stream to ~/.fennec/logs/<name>.log.

• --restart — auto-restart on crash or when the app's port stops answering. The supervisor survives your terminal closing.

• dev up — idempotent stack orchestration from fennec.config.yaml: skips apps already running with unchanged config, restarts ones whose config changed, and adopts a process that's already holding a port instead of spawning a conflicting duplicate.

• adopt — take ownership of a process an AI agent (or you) launched via raw bash, so it's tracked instead of orphaned.

• Health checks — HTTP /health probes and port liveliness drive restarts; crash-looping apps are flagged as flapping instead of spinning forever.

• inspect / log — bounded, redacted, machine-readable views purpose-built for AI consumption.

• persist — auto-start your stack after reboot/login (systemd user service + linger on Linux, launchd on macOS, startup on Windows).

• Periodic log rotation so long-running daemons don't fill your disk.

🤖 Why this matters for agents: when an agent runs npm run dev through raw bash, the process is invisible to Fennec and easy to orphan. With Fennec the agent uses process_spawn (idempotent — it adopts an existing process on the same port) or process_adopt, and gets structured status, logs, and health back. One tool call instead of five, with no double-starts.

🗄️ Database Observation

Connect to local databases (PostgreSQL, MySQL, SQLite), run read-only queries, inspect schema, check health, and get stats. Also supports rm (remove saved connection) and ps (list saved connections) CLI commands. An auto-start agent runs on connect to keep the sidecar alive. Reconnect without a URL uses the saved credential from OS keychain. Strict mode blocks non-localhost connections by default.

🔧 174+ MCP Tools Across 19 Categories

💡 Token-Efficient: Tools are categorized into 19 groups (including Mobile + AI-Native API + Debug). MCP clients can request only specific categories to reduce context window usage. Use the _categories field in ListTools response to discover available categories.

🧠 AI-Native API (Pillar 7)

Fennec's AI-Native API replaces browser-centric tools with observation-centric ones — designed for AI consumption first:

1 tool call instead of 5. 100x less tokens.

🦊 Lazy Context System — 200x Token Savings

Fennec's Lazy Context system delivers information in levels — AI never receives everything at once:

Level 0 (Pulse):  "healthy | 3 warnings | 1 critical"      ~5 tokens    ✅ Always sent
Level 1 (Summary): "Critical: DB timeout"                   ~50 tokens   ⚡ On error/request
Level 2 (Detail):  "POST /login → 500, DB connect failed"   ~200 tokens  🔍 On expand
Level 3 (Raw):     "Raw SQL, raw logs, raw DOM"             ~2000 tokens 📄 On explicit request

Config-driven: enable/disable each level via lazyContext.level1/level2/level3.

🚀 Zero-Dependency Browser Observation

Fennec supports two browser engines — choose based on your needs:

Auto-detection: Fennec tries CDP first (zero-deps). Falls back to Playwright when automation is needed.

Configure via:

{ "browser": { "adapter": "auto" | "cdp" | "playwright" } }

🔐 Auth Session Persistence

Save and load browser auth states across conversations:

# In one session
AI: auth_fill_login_form("admin@example.com", "password", submitAfter: true)
AI: auth_save_session("demo-app-prod")

# In another conversation
AI: auth_load_session("demo-app-prod")  # skip login entirely!

Sessions persist to a single global store (~/.fennec, overridable via FENNEC_HOME) and are manageable from any directory with the fennec store command. Run fennec doctor to catch secret leakage — world-readable permissions, stores living under synced directories (chezmoi/Dropbox/OneDrive), or secrets embedded in tracked launch commands.

🔍 Self-Observability

Fennec monitors its own performance — track tool call durations, memory usage, error rates. Use the PerformanceMetrics API to check Fennec's health:

Total tool calls: 1,234 | Avg duration: 45ms | Error rate: 2.3% | Memory: 128MB

🛡️ Security Model

• Sandbox mode ON by default — blocks dangerous operations

• Permission per tool — process spawn, kill, JS evaluation independently configurable

• Domain allowlist/blocklist — restrict browser navigation

• Spawn allowlist — only allow specific commands (npm, node, etc.)

• Audit log — every tool call is logged with timestamp, session, and result

• See Security Model for details

Quick Start

Installation

# Install globally
npm install -g @plumpslabs/fennec-cli

# (Optional) Install browser engines — only needed for browser automation
fennec install-browsers

# Generate config (optional)
fennec init

Note: Playwright (browser automation) is an optional peer dependency. If you only need terminal/process monitoring, Fennec works without it. Add browser support when needed:

npm install playwright
fennec install-browsers

Configure Your MCP Client

Config format depends on your client:

OpenCode (~/.config/opencode/opencode.json):

{
  "mcpServers": {
    "fennec": {
      "type": "local",
      "command": ["fennec", "start"],
      "enabled": true
    }
  }
}

Claude Desktop / Cline / Cursor / Windsurf (standard format):

{
  "mcpServers": {
    "fennec": {
      "command": "fennec",
      "args": ["start"]
    }
  }
}

For AI-driven process control, add the permission env vars:

{
  "mcpServers": {
    "fennec": {
      "command": "fennec",
      "args": ["start"],
      "env": {
        "FENNEC_SECURITY_ALLOW_PROCESS_SPAWN": "true",
        "FENNEC_SECURITY_ALLOW_PROCESS_KILL": "true"
      }
    }
  }
}

For OpenCode, add "env" inside the server entry with "type": "local" / "command" array format.

For SSE transport instead of stdio:

{
  "mcpServers": {
    "fennec": {
      "command": "fennec",
      "args": ["start", "--sse"]
    }
  }
}

OpenCode SSE config:

{
  "mcpServers": {
    "fennec": {
      "type": "remote",
      "url": "http://localhost:3333/sse",
      "enabled": true
    }
  }
}

MCP Client Compatibility

Your First Diagnosis

# Terminal: Start your app with Fennec watching
npm run dev 2>&1 | fennec pipe --name "my-app"

Then ask your AI agent:

"Check why my app is broken"

The AI will automatically:

1. Open the browser to your app

2. Check console errors

3. Inspect failed network requests

4. Correlate with server logs

5. Report the root cause

Run an app under Fennec supervision

# Launch as a supervised daemon (logs to ~/.fennec/logs/api.log)
fennec start node server.js --name api --port 8080 --restart

# Or bring up a whole stack from fennec.config.yaml (idempotent)
fennec dev up
fennec dev status

Documentation

• Getting Started Guide — includes mobile development (wireless ADB)

• Full Tool Reference — all 165+ tools documented

• Configuration Reference — all options + env vars

• Security Model — sandbox, allowlists, best practices

• Auth Flows Guide — login forms, session persistence

• Full-Stack Debugging Guide

• Multi-Session Testing Guide

• Debugging SPAs Guide

• Usage Examples

Installation Requirements

Cross-platform note: Process management (start, ps, adopt, supervisor, dev up, port discovery) works on Linux, macOS, and Windows. Linux reads /proc; macOS uses lsof/ps; Windows uses netstat/tasklist/wmic. On Windows an app's cwd isn't readable via built-ins, so it shows as empty.

Environment Variables

See the CLI README for the full command reference.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.