内容
# Fennec
### _全栈开发环境中的统一观测能力_
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
[](https://pnpm.io)
[](CONTRIBUTING.md)
**Fennec** 是一款 AI 原生的开发者观测性 MCP（模型上下文协议）服务器，为 AI 代理提供全栈开发环境的可视化能力，涵盖浏览器、终端和进程，统一在一个界面中。
## 问题
当开发者向 AI 代理询问“为什么我的登录功能坏了？”时，代理基本上是盲目的：
```text
代理看到： 开发者看到：
───────────────── ──────────────────────────────────
"我无法访问 浏览器控制台：
您的终端" ✗ TypeError: jwt.sign 未定义
"请粘贴错误 终端：
信息" ✗ 错误：环境变量 JWT_SECRET 未设置
"我没有浏览器 网络标签：
访问权限" ✗ POST /api/login -> 500
```
开发者最终成为 **复制-粘贴桥梁**，在他们的工具和 AI 之间。Fennec 消除了这一瓶颈。
## 解决方案
使用 Fennec，您的 AI 代理可以：
- 🔍 **观察** 浏览器控制台日志、网络请求和性能指标，实时监控
- 🖥️ **监视** 终端输出和服务器日志，无需更改您的工作流程
- ⚙️ **控制** 浏览器会话 — 导航、点击、输入、截图等
- 🔗 **关联** 跨层的事件，自动识别根本原因
- 🔐 **持久化** 身份验证会话，跨对话保持一致
- 🧩 **诊断** 全栈问题，单命令完成
## 运行模式
Fennec 支持三种模式，可以组合使用：
### 👀 观察（被动）
开发者正常运行服务器，Fennec 被动监听。
```bash
# 将服务器输出管道到 Fennec
npm run dev 2>&1 | fennec pipe --name "dev-server"
# 或附加到现有进程
fennec attach-pid 12345
fennec attach-port 3000
```
### 🎮 控制（主动）
AI 直接启动和管理进程。
```bash
# AI 可以：
# 1. 启动 npm run dev
# 2. 等待服务器就绪
# 3. 打开浏览器
# 4. 执行任务
# 5. 报告结果
```
### 🔀 混合（推荐）
开发者启动服务器，AI 控制浏览器 + 观察日志。
```bash
# 终端 A：运行服务器
npm run dev 2>&1 | fennec pipe --name "dev-server"
# 终端 B：AI 代理具有完全的可见性
```
## 功能
### 浏览器自动化
- 导航和交互（点击、输入、滚动、拖放）
- DOM 查询、辅助树、元素检查
- 多标签页和多上下文支持
- 截图（全页、元素、视口）
### DevTools 集成
- **控制台**：实时日志收集、过滤、错误跟踪
- **网络**：完整的请求/响应监控、拦截、模拟
- **性能**：FCP、LCP、TBT、CLS 指标、内存分析
- **存储**：localStorage、sessionStorage、cookies、IndexedDB
### 身份验证和会话
- 自动检测和填充登录表单
- 保存/加载身份验证会话，跨对话保持一致
- 多会话并行测试（例如，管理员 + 普通用户）
### 进程和终端
- 启动、监控和与进程交互
- 附加到正在运行的进程，PID 或端口
- 监视日志文件和管道流
- 自动检测日志级别（错误、警告、信息、调试）
### 🏆 全栈关联
Fennec 的标志性功能 — 将浏览器错误与服务器日志和进程状态关联，自动识别根本原因。
```json
{
"correlation": {
"rootCause": "服务器上缺少 JWT_SECRET 环境变量",
"confidence": 0.94,
"fix": "将 JWT_SECRET 添加到您的 .env 文件中",
"timeline": [
{ "t": "+0ms", "layer": "browser", "event": "POST /api/auth/login initiated" },
{ "t": "+12ms", "layer": "server", "event": "Request received at auth router" },
{ "t": "+13ms", "layer": "server", "event": "ERROR: JWT_SECRET not set" },
{ "t": "+15ms", "layer": "browser", "event": "Network failure received" },
{ "t": "+16ms", "layer": "browser", "event": "TypeError thrown in auth.js:67" }
]
}
}
```
## 文档
- [快速入门指南](docs/getting-started.md)
- [完整工具参考](docs/tools/README.md) — 90+ MCP 工具，涵盖 12 个组
- [指南](docs/guides/)
- [身份验证流程](docs/guides/auth-flows.md) — 登录表单、会话持久性、多用户
- [调试 SPA](docs/guides/debugging-spa.md) — React、Vue、Next.js 调试
- [全栈调试](docs/guides/fullstack-debugging.md) — 关联浏览器 ↔ 服务器错误
- [多会话测试](docs/guides/multi-session.md) — 并行隔离会话
- [安全模型](docs/security-model.md) — 沙箱、允许列表、最佳实践
- [配置参考](docs/configuration.md) — 所有配置选项 + 环境变量
- [使用示例](examples/) — 逐步 JSON-RPC 演练
## 安装和设置
### 先决条件
| 需求 | 版本 |
|---|---|
| **Node.js** | >= 20.0.0 |
| **npm** / **pnpm** / **yarn** | 最新稳定版 |
| **操作系统** | macOS、Linux、Windows（推荐 WSL2） |
### 选项 1：快速安装（推荐）
```bash
# 1. 全局安装
npm install -g @plumpslabs/fennec-cli
# 2. 安装浏览器引擎（Playwright Chromium）
fennec install-browsers
# 3. 生成配置文件（可选）
fennec init
```
### 选项 2：从源代码
```bash
git clone https://github.com/plumpslabs/fennec.git
cd fennec
pnpm install
pnpm build
npx playwright install chromium --with-deps
```
### 配置您的 MCP 客户端
Fennec 作为 MCP 服务器运行。将以下块添加到您的 MCP 客户端的配置文件中 — **客户端将在需要时自动启动 Fennec**：
```json
{
"mcpServers": {
"fennec": {
"command": "fennec",
"args": ["start"]
}
}
}
```
无需手动运行 `fennec start`。配置文件位置因客户端而异：
| 客户端 | 配置文件 |
|---|---|
| Claude Desktop | `claude_desktop_config.json` |
| Claude Code | `~/.claude/settings.json` |
| Cline (VS Code) | `cline_mcp_settings.json` |
| Cursor | `.cursor/mcp.json` |
| Windsurf | `mcp_config.json` |
| Continue.dev | `config.json` |
或运行引导设置：
```bash
fennec setup
```
### 验证其是否有效（可选）
在独立测试 Fennec（无需 MCP 客户端）：
```bash
fennec start
```
然后在另一个终端：
```bash
npx @modelcontextprotocol/inspector fennec start
```
## 快速入门：您的第一个诊断
一旦 Fennec 运行并连接到您的 AI 代理，请尝试此工作流程：
```bash
# 终端：使用 Fennec 监视启动您的应用程序
npm run dev 2>&1 | fennec pipe --name "my-app"
```
然后询问您的 AI 代理：
> "检查我的应用程序为什么损坏"
AI 将自动使用 Fennec 工具：
1. 打开浏览器访问您的应用程序
2. 检查控制台错误
3. 检查失败的网络请求
4. 与服务器日志关联
5. 报告根本原因
## 您需要设置的项
| 步骤 | 内容 | 是否必需 | 备注 |
|---|---|---|---|
| 1 | 安装 Node.js >= 20 | ✅ 是 | [nodejs.org](https://nodejs.org) |
| 2 | 安装 `@plumpslabs/fennec-cli` | ✅ 是 | `npm install -g @plumpslabs/fennec-cli` |
| 3 | 安装 Playwright 浏览器 | ✅ 是 | `fennec install-browsers`（仅 Chromium） |
| 4 | MCP 客户端（Claude Desktop 等） | ✅ 是 | 用于 AI 代理集成 |
| 5 | 配置文件 | 可选 | `fennec init` 进行自定义 |
| 6 | 管道服务器输出 | 可选 | `| fennec pipe --name "my-app"` 用于服务器日志 |
| 7 | 设置环境变量 | 可选 | 参见 [configuration docs](docs/configuration.md) |
## 贡献
我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
## 许可证
MIT — 详情参见 [LICENSE](LICENSE)。
---
<div align="center">
<small>
Fennec — <em>全栈开发环境中的统一观测能力。</em><br>
由 ❤️ 为 AI 原生开发构建
</small>
</div>
