Skip to main content
Glama
@chenpu17/web-bridge-mcp

@chenpu17/web-bridge-mcp

by chenpu17
README.md
# @chenpu17/web-bridge-mcp

[![npm version](https://badge.fury.io/js/@chenpu%2Fweb-bridge-mcp.svg)](https://badge.fury.io/js/@chenpu%2Fweb-bridge-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

支持代理配置的 MCP Server,提供 Web 搜索、网页抓取,以及官方 Context7 文档能力透传。

**专为内网环境设计**,让无法直接访问外网的 AI 编程工具(如 Claude Code、OpenCode)也能获取互联网信息。

## 特性

- **代理支持**: 支持 `system`(自动检测系统代理)、`none`(不使用代理)、自定义代理 URL
- **Windows 系统代理检测**: 自动读取 Windows 注册表获取系统代理配置
- **SSL 证书忽略**: 支持忽略 SSL 证书校验,解决代理导致的证书问题
- **多种搜索引擎**: DuckDuckGo(免费)、Exa AI、博查 AI
- **网页抓取**: 支持 Markdown、纯文本、HTML 格式输出
- **官方 Context7 透传**: 直连 `https://mcp.context7.com/mcp`,暴露官方 `resolve-library-id` / `query-docs` 工具
- **Context7 默认开启**: 启动后默认同时暴露搜索、抓取、Context7 文档工具,无需额外参数
- **Context7 可选鉴权**: 支持 `CONTEXT7_API_KEY`,不配置也可匿名基础使用
- **Context7 容错更稳**: 远端工具发现失败时保留内置 fallback 元数据,临时网络抖动时自动重连重试一次
- **npx 运行**: 无需安装,一条命令即可使用

## 快速开始

```bash
# 使用 npx 直接运行(推荐)
npx @chenpu17/web-bridge-mcp --proxy system --ignore-ssl

# 或全局安装
npm install -g @chenpu17/web-bridge-mcp
web-bridge-mcp --proxy system --ignore-ssl
```

## 使用方法

### 基本用法

```bash
# 使用 DuckDuckGo 搜索(默认,免费无需配置)
npx @chenpu17/web-bridge-mcp

# 使用系统代理
npx @chenpu17/web-bridge-mcp --proxy system

# 指定代理地址
npx @chenpu17/web-bridge-mcp --proxy http://proxy.company.com:8080

# 忽略 SSL 证书校验(解决代理证书问题)
npx @chenpu17/web-bridge-mcp --proxy system --ignore-ssl
```

### 启用 Context7

```bash
# Context7 默认已启用
npx @chenpu17/web-bridge-mcp

# 内网推荐:系统代理 + 忽略 SSL + Context7
npx @chenpu17/web-bridge-mcp --proxy system --ignore-ssl

# 配置 Context7 API Key(可选,提高限额)
npx @chenpu17/web-bridge-mcp --proxy system --ignore-ssl --context7-api-key ctx7sk_xxx

# 如需显式关闭 Context7
npx @chenpu17/web-bridge-mcp --no-context7
```

### 搜索引擎配置

```bash
# DuckDuckGo(默认,免费)
npx @chenpu17/web-bridge-mcp --web-search duckduckgo

# Exa AI(AI 优化搜索)
npx @chenpu17/web-bridge-mcp --web-search exa

# 博查 AI(中文友好,需要 API Key)
npx @chenpu17/web-bridge-mcp --web-search bocha --bocha-api-key sk-xxx
```

### 完整示例(企业内网推荐配置)

```bash
# 使用系统代理 + 忽略 SSL + DuckDuckGo + 官方 Context7
npx @chenpu17/web-bridge-mcp --proxy system --ignore-ssl

# 使用系统代理 + 忽略 SSL + 博查搜索 + 官方 Context7
npx @chenpu17/web-bridge-mcp --proxy system --ignore-ssl --web-search bocha --bocha-api-key sk-xxx
```

### 环境变量

| 变量名 | 说明 |
|--------|------|
| `HTTPS_PROXY` / `HTTP_PROXY` | 代理地址 |
| `BOCHA_API_KEY` | 博查 AI 的 Bearer Token |
| `CONTEXT7_API_KEY` | Context7 API Key(可选) |
| `CONTEXT7_MCP_URL` | Context7 MCP URL,默认 `https://mcp.context7.com/mcp` |
| `ENABLE_CONTEXT7` | 是否启用 Context7;默认启用,设置为 `false` 可关闭 |
| `IGNORE_SSL` | 忽略 SSL 证书校验 (设置为 `true`) |
| `NODE_TLS_REJECT_UNAUTHORIZED` | 设置为 `0` 也可忽略 SSL |

### 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-p, --proxy <proxy>` | 代理设置: system \| none \| http://... | none |
| `--web-search <engine>` | 搜索引擎: duckduckgo \| exa \| bocha | duckduckgo |
| `--bocha-api-key <key>` | 博查 AI API Key | - |
| `-t, --timeout <ms>` | 请求超时时间(毫秒) | 30000 |
| `--ignore-ssl` | 忽略 SSL 证书校验 | false |
| `--no-context7` | 禁用官方 Context7 MCP 透传 | 默认启用 |
| `--context7-api-key <key>` | Context7 API Key(可选) | - |
| `--context7-url <url>` | Context7 MCP URL | `https://mcp.context7.com/mcp` |

### 检测系统代理

```bash
npx @chenpu17/web-bridge-mcp detect-proxy
```

### 诊断代理连接

测试代理配置是否正常工作,包括连接测试、搜索测试和抓取测试:

```bash
# 使用系统代理进行诊断
npx @chenpu17/web-bridge-mcp diagnose

# 使用指定代理进行诊断
npx @chenpu17/web-bridge-mcp diagnose --proxy http://proxy.company.com:8080

# 忽略 SSL 证书进行诊断
npx @chenpu17/web-bridge-mcp diagnose --proxy system --ignore-ssl

# 默认会额外测试 Context7 连通性
npx @chenpu17/web-bridge-mcp diagnose --proxy system --ignore-ssl

# 如需跳过 Context7 测试
npx @chenpu17/web-bridge-mcp diagnose --proxy system --ignore-ssl --no-context7
```

诊断命令会自动测试:
1. 代理检测 - 检查代理配置是否正确
2. 连接测试 - 测试是否能通过代理访问互联网
3. 搜索测试 - 测试 DuckDuckGo 搜索功能
4. 抓取测试 - 测试网页内容抓取功能
5. Context7 测试(默认启用)- 测试官方 Context7 工具发现与调用

每个步骤都会显示详细的测试结果和响应时间,帮助快速定位问题。

如果你准备发布新版本,建议在本机或目标网络环境里至少手动跑一次 `diagnose`,确认代理、匿名访问或 API Key 配置都正常。

## MCP 工具

### web_search

搜索互联网获取信息。

**参数**:
- `query` (string): 搜索查询内容
- `numResults` (number, 可选): 返回结果数量,默认 8

### web_fetch

抓取指定 URL 的网页内容。

**参数**:
- `url` (string): 要抓取的 URL
- `format` (enum, 可选): 返回格式 - markdown / text / html,默认 markdown
- `timeout` (number, 可选): 超时时间(秒),最大 120

### resolve-library-id

官方 Context7 工具,解析库名并返回 Context7 兼容的 library ID。

**参数**:
- `query` (string): 当前要完成的任务或问题
- `libraryName` (string): 要查找的库名

### query-docs

官方 Context7 工具,根据 library ID 检索最新文档和代码示例。

**参数**:
- `libraryId` (string): Context7 兼容库 ID,例如 `/vercel/next.js`
- `query` (string): 具体问题或任务

## 在 Claude Code 中使用

在 Claude Code 的配置文件中添加 MCP Server:

```json
{
  "mcpServers": {
    "proxy-web": {
      "command": "npx",
      "args": [
        "@chenpu17/web-bridge-mcp",
        "--proxy", "system",
        "--ignore-ssl",
        "--web-search", "duckduckgo"
      ]
    }
  }
}
```

如果使用博查搜索:

```json
{
  "mcpServers": {
    "proxy-web": {
      "command": "npx",
      "args": [
        "@chenpu17/web-bridge-mcp",
        "--proxy", "system",
        "--ignore-ssl",
        "--web-search", "bocha",
        "--bocha-api-key", "sk-xxx"
      ]
    }
  }
}
```

如果 Context7 需要更高限额,可追加 API Key:

```json
{
  "mcpServers": {
    "proxy-web": {
      "command": "npx",
      "args": [
        "@chenpu17/web-bridge-mcp",
        "--proxy", "system",
        "--ignore-ssl",
        "--context7-api-key", "ctx7sk_xxx"
      ]
    }
  }
}
```

## 搜索引擎对比

| 搜索引擎 | 免费 | 鉴权方式 | 特点 |
|---------|------|---------|------|
| DuckDuckGo | ✅ | 无需 | 免费、无限制,结果质量一般 |
| Exa AI | ❌ | 无需(MCP端点) | AI 优化搜索,结果质量高 |
| 博查 AI | ❌ | Bearer Token | 中文搜索友好 |

## 常见问题

### 1. 代理证书错误

如果遇到 `UNABLE_TO_VERIFY_LEAF_SIGNATURE` 错误,请添加 `--ignore-ssl` 参数:

```bash
npx @chenpu17/web-bridge-mcp --proxy system --ignore-ssl
```

### 2. Windows 系统代理未检测到

确保系统代理已正确配置:
1. 打开「设置」→「网络和 Internet」→「代理」
2. 检查「使用代理服务器」是否已开启

### 3. 博查搜索认证失败

确保 API Key 正确,可以通过环境变量或命令行参数配置:

```bash
# 方式1: 命令行参数
npx @chenpu17/web-bridge-mcp --web-search bocha --bocha-api-key sk-xxx

# 方式2: 环境变量
export BOCHA_API_KEY=sk-xxx
npx @chenpu17/web-bridge-mcp --web-search bocha
```

### 4. Context7 是否必须鉴权?

不是必须。官方远端 MCP 在很多场景下支持匿名基础使用,但限额更低。

如果你在企业内网长期使用,建议配置 `CONTEXT7_API_KEY` 或 `--context7-api-key`,这样更稳定,也更接近官方推荐方式:

```bash
export CONTEXT7_API_KEY=ctx7sk_xxx
npx @chenpu17/web-bridge-mcp --proxy system --ignore-ssl
```

## 开发

```bash
# 克隆仓库
git clone https://github.com/chenpu/web-bridge-mcp.git
cd web-bridge-mcp

# 安装依赖
npm install

# 开发模式
npm run dev -- --proxy system --ignore-ssl

# 构建
npm run build

# 运行构建产物
npm start -- --proxy system --ignore-ssl

# 运行测试
npm test

# 代码质量检查
npm run lint

# 格式化代码
npm run format

# 类型检查
npm run typecheck
```

## 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 运行测试确保通过 (`npm test`)
4. 运行 lint 检查 (`npm run lint`)
5. 提交更改
6. 推送到分支
7. 创建 Pull Request

## 技术栈

- **Runtime**: Node.js >= 18
- **Language**: TypeScript
- **Framework**: MCP SDK
- **Testing**: Vitest
- **Linting**: ESLint + TypeScript ESLint
- **Formatting**: Prettier

## 安全性

### SSRF 防护

本项目实现了多层 SSRF (Server-Side Request Forgery) 防护:

- **内网 IP 段阻止**: 自动阻止访问私有 IP 地址
- **敏感端口过滤**: 禁止访问数据库、邮件等敏感服务端口
- **IPv6 支持**: 同时检测 IPv4 和 IPv6 内网地址
- **本地地址拦截**: 阻止 localhost 和本地回环地址

### 最佳实践

- 使用环境变量存储敏感信息(API Keys)
- 支持忽略 SSL 证书校验(仅限受信任的网络环境)
- 响应大小限制(5MB)
- 请求超时控制

## License

MIT © chenpu

TDQS

A4.4/5.0

Scored across 4 tools

Disambiguation4/5

The tools are clearly separated by purpose: web_search vs web_fetch are distinct (search vs retrieve URL), and resolve-library-id vs query-docs are distinct (resolve ID vs query docs). There is slight overlap between web_search and resolve-library-id for library queries, but explicit guidance to prefer Context7 tools resolves this ambiguity.

Naming Consistency2/5

The naming convention is inconsistent: web_search and web_fetch use snake_case with verb_noun pattern, while resolve-library-id and query-docs use kebab-case. This mixed pattern (underscore vs hyphen) creates a lack of uniformity across the tool set, making it harder to anticipate tool names.

Tool Count5/5

With only 4 tools, the set is tightly scoped for a web-bridge purpose: one search, one fetch, one library resolver, and one doc query tool. Each tool earns its place, and the count is well within the ideal 3-15 range.

Completeness5/5

The set covers complete workflows: general web search leads to web_fetch for content retrieval, and library resolution leads to query-docs for documentation. No obvious dead ends or missing operations are apparent for the stated hybrid purpose of bridging general web and library documentation access.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues