Pinchtab MCP Wrapper

夹管式MCP包装器

一个MCP（模型上下文协议）服务器，它公开了完整的 夹片 浏览器API到AI编码代理。考虑到令牌效率，非常适合数据提取、网络抓取和自动化测试工作流程。

______________________________________________________________________

为什么要为AI代理使用Pinchtab？

当AI代理需要浏览网页时，效率很重要。Pinchtab提供 节省5-13x的成本 与传统的浏览器自动化相比。

成本比较（实际数字）

人工智能工作流程的主要优势

1.数据提取和网页抓取

• 提取干净、结构化的文本，无需HTML开销
• 可访问性树提供语义结构（角色、标签、状态）
• 仅在需要时过滤交互式元素

2.网站变更监控

• diff=true 仅返回自上次快照以来更改的元素
• 跟踪价格变化、内容更新或可用性
• 监控50多个页面，无上下文溢出

3.异步多标签操作

• 同时运行20+个标签页（相比之下，Playwright为3-5个）
• 标签锁定可防止代理之间的冲突
• 每个选项卡~1MB RAM，而完整浏览器实例为50MB+

4.稳定的自动化

• 稳定元素引用(e0, e1)在CSS更改中幸存下来
• 没有脆弱的CSS选择器会在重新设计时中断
• 适用于阻止传统自动化的网站（隐形模式）

______________________________________________________________________

快速开始

单线安装

curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

要求： Docker、Node.js 18+、npm

然后重启你的AI代理（OpenCode、Claude Code等）

测试IT

Open https://example.com and take a screenshot

或使用命令：

/browse https://example.com
/screenshot

______________________________________________________________________

用例和示例

1.大规模的网络抓取

问题： 从100个电子商务页面中提取产品价格

传统方法：

• 加载完整DOM（每页约10000个令牌）
• 手动解析HTML
• 成本：1000000个代币（约3.00美元）

夹管法：

// Extract structured text only
pinchtab_read_page({url: "https://store.com/product"})
// Returns clean text with prices, descriptions

• 成本：80000个代币（约0.24美元）
• 节省：2.76美元（便宜12.5倍）

2.变更检测与监控

问题： 监控竞争对手的价格或新闻更新

// First visit - establish baseline
snapshot1 = pinchtab_snapshot({url: "https://competitor.com/prices"})

// Later visits - get only changes
diff = pinchtab_snapshot({
  url: "https://competitor.com/prices", 
  diff: true
})
// Returns only modified elements (50-200 tokens vs 10,000)

优点：

• 跟踪50个站点，无上下文溢出
• 即时检测变化
• 数据传输量减少200倍

3.多源研究

问题： 同时从10多个文档网站收集信息

// Open multiple tabs in parallel
tab1 = pinchtab_tab_open({url: "https://docs.api1.com"})
tab2 = pinchtab_tab_open({url: "https://docs.api2.com"})
tab3 = pinchtab_tab_open({url: "https://docs.api3.com"})

// Extract text from all tabs
text1 = pinchtab_read_page({tabId: tab1.tabId})
text2 = pinchtab_read_page({tabId: tab2.tabId})
text3 = pinchtab_read_page({tabId: tab3.tabId})

优点：

• 20+个并发选项卡
• 无内存问题（每个标签1MB）
• 异步操作

4.持久的表单自动化

问题： 自动化在网站更新时中断的登录/结账流程

传统选择器中断：

// Brittle - breaks when CSS changes
await page.click('#login-btn')  // ❌

夹管稳定参考：

// Stable - survives redesigns
pinchtab_action({
  tabId: "...",
  kind: "click",
  ref: "e5"  // ✅ Persistent reference
})

5.可访问性优先测试

内置可访问性树：

• 元素角色（按钮、链接、标题）
• 可访问的名称和标签
• 焦点状态和可见性
• 兼容屏幕阅读器

// Get only interactive elements
interactives = pinchtab_list_interactives()
// Returns: buttons, links, inputs with labels

______________________________________________________________________

可用工具

______________________________________________________________________

CLI集成

开源代码

添加 ~/.config/opencode/opencode.json:

{
  "\$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pinchtab": {
      "type": "local",
      "command": [
        "/usr/bin/node",
        "~/.pinchtab-mcp-wrapper/dist/index.js"
      ],
      "environment": {
        "PINCHTAB_MODE": "external",
        "PINCHTAB_URL": "http://127.0.0.1:9867",
        "PINCHTAB_TOKEN": "opencode-browser-token-secure",
        "MCP_TRANSPORT": "stdio",
        "LOG_LEVEL": "info"
      },
      "enabled": true
    }
  },
  "agent": {
    "browser": {
      "description": "Browser automation specialist",
      "prompt": "Use pinchtab MCP tools for all web browsing tasks. Prefer text extraction over screenshots for efficiency.",
      "tools": {
        "pinchtab*": true,
        "playwright*": false
      }
    }
  },
  "default_agent": "browser"
}

先决条件： 确保Pinchtab Docker容器正在运行：

docker ps | grep pinchtab  # Check if running
docker start pinchtab       # Start if stopped

克劳德代码

添加 .mcp.json:

{
  "mcpServers": {
    "pinchtab": {
      "command": "bash",
      "args": ["~/.pinchtab-mcp-wrapper/run-mcp.sh"]
    }
  }
}

克劳德代码技能（实验）： 我们还为Claude Code CLI用户提供了一个技能文件。看 CLAUDE_CODE_SKILL.md 有关西班牙语的详细安装和使用说明。您可以将此文件保存到 ~/.claude/commands/pinchtab.md 和使用 /pinchtab 直接在CLI中访问完整参考。

光标

添加到Cursor的MCP设置（设置→ 特性→ MCP):

{
  "mcpServers": {
    "pinchtab": {
      "type": "stdio",
      "command": "bash",
      "args": ["~/.pinchtab-mcp-wrapper/run-mcp.sh"]
    }
  }
}

泽德

添加 ~/.config/zed/settings.json:

{
  "assistant": {
    "version": "2",
    "enabled": true
  },
  "context_servers": {
    "pinchtab": {
      "command": "bash",
      "args": ["~/.pinchtab-mcp-wrapper/run-mcp.sh"]
    }
  }
}

______________________________________________________________________

______________________________________________________________________

多个AI代理的自动配置

安装程序现在可以自动检测并配置多个AI代理的pinchtab：

• 开源代码 (~/.config/opencode/opencode.json)
• 克劳德代码 (~/.mcp.json 或 ./.mcp.json)
• 光标 (~/.config/Cursor/User/settings.json)
• 泽德 (~/.config/zed/settings.json)

如果配置文件已经存在，安装程序将：

1. 创建备份(.backup.YYYYMMDD_HHMMSS)
2. 使用Node.js自动合并pinchtab配置
3. 保留所有现有设置

无需手动编辑-只需运行安装程序并重新启动AI代理！

安装选项

安装脚本现在支持自动模式检测和优雅回退：

自动模式（默认）

安装程序会自动检测您的环境并选择最佳模式：

curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

发生了什么：

1. 检查Docker（包括macOS特定路径：Homebrew、OrbStack、Docker Desktop）
2. 如果Docker可用→ 构建Docker镜像并使用 docker 模式
3. 如果Docker不可用→ 自动下载Pinchtab二进制文件并使用 external 模式

Docker模式

推荐给大多数用户。需要安装Docker。

export PINCHTAB_MODE=docker
curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

外部模式（二进制）

对于没有Docker的系统。安装程序会自动下载适用于您架构的Pinchtab二进制文件。

export PINCHTAB_MODE=external
curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

macOS支持

安装程序会在以下位置自动检测Docker：

• /opt/homebrew/bin/docker （苹果硅上的自制）
• /usr/local/bin/docker （英特尔自制）
• /Applications/OrbStack.app/Contents/MacOS/../bin/docker （OrbStack）
• /Applications/Docker.app/Contents/Resources/bin/docker （Docker桌面）
• ~/.docker/bin/docker （Docker桌面替代品）

您还可以手动指定Docker路径：

export DOCKER_PATH=/opt/homebrew/bin/docker
curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

手动安装

# Clone
git clone https://github.com/BDuba/pinchtab-mcp-wrapper.git
cd pinchtab-mcp-wrapper

# Build
npm install && npm run build

# Build Docker image
docker build -f pinchtab.Dockerfile -t pinchtab:local .

# Create wrapper
cat > run-mcp.sh ` 或api密钥的原始令牌|
| `Content-Type` |是的| `application/json` |
| `Mcp-Session-Id` |可选|状态模式的会话ID|

**身份验证示例：**

Bearer token auth

curl -H "Authorization: Bearer your-secret-token" \ http://localhost:3000/mcp

API key auth (header)

curl -H "Authorization: your-api-key" \ http://localhost:3000/mcp

API key auth (query param)

curl "http://localhost:3000/mcp?api_key=your-api-key"

**从AI代理连接：**

大多数MCP客户端本机支持Streamable HTTP。使用以下配置您的AI代理：

{ "mcp": { "pinchtab": { "type": "http", "url": "http://your-server:3000/mcp", "headers": { "Authorization": "Bearer your-secret-token" } } } }

#### 使用一个Pinchtab实例运行多个AI代理

**脚本：** 您有多个AI代理（OpenCode、LobeChat、Claude Code、Cursor等），并希望为所有这些代理使用一个Pinchtab Docker容器。

**问题：** 每个AI代理可能需要不同的MCP传输（CLI代理需要stdio，基于服务器的代理需要HTTP）。

**解决方案：** 将一个Pinchtab容器与多个MCP服务器一起使用：

┌─────────────────────────────────────────────────────────────┐ │ Pinchtab Docker Container │ │ (http://127.0.0.1:9867) │ └─────────────────────────┬───────────────────────────────────┘ │ ┌─────────────────────────▼───────────────────────────────────┐ │ MCP Wrapper HTTP Server │ │ (http://0.0.0.0:3001/mcp) │ │ • LobeChat ───────┐ • Other HTTP clients ───┐ │ │ • Remote agents ──┘ • Cloud services ───────┘ │ └─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐ │ MCP Wrapper stdio Servers │ │ • OpenCode ───────┐ • Claude Code ───────┐ │ │ • Cursor ─────────┘ • Zed ───────────────┘ │ └─────────────────────────────────────────────────────────────┘

**设置步骤：**

1. **启动Pinchtab Docker容器：**

docker run -d \ --name pinchtab \ -p 127.0.0.1:9867:9867 \ -e PINCHTAB_TOKEN=opencode-browser-token-secure \ pinchtab:local

2. **为基于服务器的代理（LobeChat等）启动HTTP MCP服务器：**

export PINCHTAB_MODE=external export PINCHTAB_URL=http://127.0.0.1:9867 export PINCHTAB_TOKEN=opencode-browser-token-secure export MCP_TRANSPORT=streamable-http export MCP_HTTP_PORT=3001 export MCP_HTTP_HOST=0.0.0.0 export MCP_AUTH_TYPE=none export MCP_ENABLE_SESSIONS=true node dist/index.js

3. **配置CLI代理（OpenCode、Claude Code、Cursor、Zed）以使用stdio：**

   - OpenCode： `~/.config/opencode/opencode.json` （参见 [OpenCode部分](#opencode))
   - 克劳德代码： `.mcp.json` （参见 [克劳德代码部分](#claude-code))
   - 光标：MCP设置（请参见 [光标部分](#cursor))
   - Zed： `~/.config/zed/settings.json` （参见 [Zed段](#zed))

1. **配置基于服务器的代理（LobeChat）以使用HTTP：**

   - 网址： `http://172.21.0.1:3001/mcp`
   - 类型： `Streamable HTTP`
   - 认证： `None`

**优点：**

- **单个Pinchtab实例** 适用于所有AI代理
- **无端口冲突** （stdio用于CLI，HTTP用于服务器）
- **资源效率的** （一个浏览器实例）
- **浏览器状态一致** 所有代理

**使HTTP MCP服务器持久化：**

sudo tee /etc/systemd/system/pinchtab-mcp.service << 'EOF' [Unit] Description=Pinchtab MCP HTTP Server After=network.target docker.service

[Service] Type=simple User=root WorkingDirectory=/root/.pinchtab-mcp-wrapper ExecStart=/bin/bash -c 'export PINCHTAB_MODE=external && export PINCHTAB_URL=http://127.0.0.1:9867 && export PINCHTAB_TOKEN=opencode-browser-token-secure && export MCP_TRANSPORT=streamable-http && export MCP_HTTP_PORT=3001 && export MCP_HTTP_HOST=0.0.0.0 && export MCP_AUTH_TYPE=none && export MCP_ENABLE_SESSIONS=true && node dist/index.js' Restart=always RestartSec=5

[Install] WantedBy=multi-user.target EOF

sudo systemctl daemon-reload sudo systemctl enable pinchtab-mcp sudo systemctl start pinchtab-mcp

### Pinchtab选项（通过Docker）

### Pinchtab选项（通过Docker）

PINCHTAB_MODE=docker # docker | external PINCHTAB_TOKEN=secret-token # Auth token DEFAULT_SNAPSHOT_FORMAT=compact # compact | text | json DEFAULT_MAX_TOKENS=2500 # Token budget SCREENSHOT_DEFAULT_DELIVERY=base64 # base64 | s3 | file

### Pinchtab选项（通过Docker）

BRIDGE_STEALTH=full # Bypass bot detection BRIDGE_BLOCK_IMAGES=true # Faster loading BRIDGE_NO_ANIMATIONS=true # Consistent snapshots BRIDGE_TIMEOUT=30 # Action timeout (seconds)

______________________________________________________________________

## 故障排除

|问题|解决方案|
|-------|----------|
|“连接已关闭”|检查 `docker ps`，验证容器是否正在运行|
|“MCP错误-32000”|完全重新启动AI代理|
|健康检查超时| `docker logs pinchtab` 对于错误|
|401错误|验证PINCHTAB_TOKEN匹配|

______________________________________________________________________

## 代币效率指南

**降低成本的最佳实践：**

1. **使用 `/text` 用于阅读** -800个代币vs 10000个DOM代币
1. **过滤交互** -3600个代币vs 10500个整页代币
1. **使用 `diff=true`** -仅更改了元素（50-200个令牌）
1. **阻止图像/媒体** -加载速度更快，噪音更小
1. **锁定标签** -防止冲突，避免返工

______________________________________________________________________

## 发展

npm install npm run build npm test

______________________________________________________________________

## 发布历史

看 [更改日志.md](CHANGELOG.md) 查看详细的版本历史和更改。

**最新版本**：v0.6.1（2026-03-19）

- **E2E HTTP测试稳定性** -修复了HTTP模式E2E测试中的间歇性超时问题
- 包含v0.6.0的所有功能

**以前版本（v0.6.0）**:

- **Pinchtab v0.7.8支持** -更新到稳定的Pinchtab版本
- **修复了MCP流式HTTP传输** -提高了连接稳定性和错误处理能力

**先前版本**:

- v0.5.1-Pinchtab v0.6.3支持，文件上传工具
- v0.5.0-可流式HTTP传输，多传输架构
- v0.4.0-CI/CD管道、ESLint、综合测试套件
- v0.2.0-下载工具，Pinchtab 0.6.1，多代理配置

______________________________________________________________________

## 学分和许可证

此MCP包装器基于 [夹片](https://github.com/pinchtab/pinchtab) 路易吉·阿戈斯蒂和撰稿人。

- 夹片： 
- MCP协议： [模型上下文协议.io](https://modelcontextprotocol.io/)

MIT许可证