Setup Guide

使用指南

从安装到运行，完整的 Grabby 配置流程。

前置要求

  • - Chrome 浏览器（或基于 Chromium 的浏览器）
  • - Node.js — 用于构建浏览器扩展
  • - Python 3.13+ 或 Go 1.23+ — 后端运行环境（二选一）

1. 克隆项目

git clone https://github.com/gusibi/grabby.git
cd grabby

2. 安装浏览器扩展

方式一：Chrome 网上应用店（推荐）

一键安装，自动更新。

安装 Grabby 扩展

方式二：开发模式加载

如果你需要修改源码或进行开发调试：

  1. 打开 Chrome，访问 chrome://extensions
  2. 开启右上角 "开发者模式"
  3. 点击 "加载已解压的扩展程序"
  4. 选择项目中的 chrome-extension/ 目录

3. 安装后端服务

Python 后端（推荐新手）

使用 uv 包管理器一键运行，自动处理虚拟环境和依赖安装：

1) 安装 uv（如未安装）

curl -LsSf https://astral.sh/uv/install.sh | sh

2) 配置环境变量

cd python-server
cp .env.example .env

编辑 .env 文件，按需修改以下配置：

配置项 默认值 说明
HOST 0.0.0.0 服务器监听地址
PORT 5040 服务器监听端口
CONNECT_ID browser-tools 浏览器扩展连接 ID，两端必须一致
API_KEY （空） HTTP/WebSocket 端点保护密钥，留空表示关闭校验
DEBUG false 调试模式，开启后输出更多日志
WEBSOCKET_TIMEOUT 5.0 WebSocket 请求超时（秒）
API_EXTRACT_TIMEOUT 60.0 HTTP API extract 端点超时（秒）
DEFAULT_BROWSER （空） 默认浏览器名称，留空使用第一个连接的浏览器

配置优先级：系统环境变量 > .env 文件 > 代码默认值

3) 启动服务

"text-[#8b949e]"># 方式一：使用 uv 直接运行（推荐）
uv run python main.py

"text-[#8b949e]"># 方式二：使用启动脚本（自动检测 Python/Go 后端）
cd ..
./start.sh

服务启动后，控制台会输出可用端点：

HTTP API:
  POST http://localhost:5040/api/extract    - 提取网页 Markdown
  GET  http://localhost:5040/api/health     - 健康检查
  GET  http://localhost:5040/api/browsers   - 已连接浏览器列表

WebSocket:
  ws://localhost:5040/ws_browser  - 浏览器扩展连接

MCP Server:
  http://localhost:5040/mcp/sse

Go 后端（推荐资源受限环境）

cd go-server
cp .env.example .env
"text-[#8b949e]"># 编辑 .env 按需修改配置（配置项与 Python 后端一致）

go build -o go-server .
./go-server

Go 后端支持交叉编译：

"text-[#8b949e]"># macOS ARM64
GOOS=darwin GOARCH=arm64 go build -o go-server-darwin .

"text-[#8b949e]"># Linux AMD64
GOOS=linux GOARCH=amd64 go build -o go-server-linux .

"text-[#8b949e]"># Windows
GOOS=windows GOARCH=amd64 go build -o go-server.exe .

4. 配置扩展

打开设置页面

右键点击 Chrome 工具栏中的 Grabby 图标 → 选项 / Options

填写连接信息

字段 示例值 说明
WebSocket 服务器地址 ws://localhost:5040/ws_browser 后端 WebSocket 端点，与服务端 HOST:PORT 对应
API 密钥 browser-tools 必须与服务端 .env 中的 CONNECT_ID 一致
浏览器名称 chrome-office 多浏览器场景下的标识名称（可选，单浏览器留空）
启动时自动连接 勾选 推荐开启，Chrome 启动后自动连接后端服务

认证原理

扩展连接时，会将 API 密钥 作为 conn_id 参数附加到 WebSocket URL：

ws://localhost:5040/ws_browser?conn_id=browser-tools

服务端验证 conn_id 是否与 .env 中的 CONNECT_ID 匹配。不一致则拒绝连接（返回 403）。因此扩展的 API 密钥必须与服务端的 CONNECT_ID 保持一致。

保存并连接

  1. 填写上述字段
  2. 点击页面底部的 保存设置
  3. 扩展自动尝试连接后端服务
  4. 看到 "连接状态：已连接" 即表示成功

5. 验证安装

健康检查

curl http://localhost:5040/api/health

"text-[#8b949e]"># 预期响应
{"text-[#7ee787]">"status": "text-[#a5d6ff]">"ok","text-[#7ee787]">"browser_connected": "text-[#ff7b72]">true,"text-[#7ee787]">"timestamp": "text-[#a5d6ff]">"..."}

测试提取

curl -X POST http://localhost:5040/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

"text-[#8b949e]"># 预期响应
{"text-[#7ee787]">"success": "text-[#ff7b72]">true,"text-[#7ee787]">"url": "text-[#a5d6ff]">"https://example.com","text-[#7ee787]">"title": "text-[#a5d6ff]">"Example Domain","text-[#7ee787]">"markdown": "text-[#a5d6ff]">"# Example Domain\n\n..."}

6. 配置 Claude Desktop

在 Claude Desktop 的配置文件中添加 Grabby MCP Server：

{
  "mcpServers": {
    "grabby": {
      "url": "http://localhost: 5040/mcp/sse"
    }
  }
}

配置文件位置：~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

常见问题

扩展无法连接服务器

  1. 确认后端服务已启动
  2. 检查 WebSocket 地址和端口是否正确
  3. 确认 API 密钥与服务器 .env 中的配置一致
  4. 检查防火墙是否放行端口

Python 依赖安装失败

推荐使用 uv 替代 pip，uv 会自动创建虚拟环境并解析依赖。

Go 编译失败

确保 Go 版本 >= 1.23。如果模块下载失败，设置代理：go env -w GOPROXY=https://goproxy.cn,direct