中文 | English

Local Web Search Agent

为 Claude Code 和 OpenCode 提供网络搜索能力的 MCP Server，并附带 Claude Code 子代理模板。

简介

本项目通过 MCP (Model Context Protocol) 为 Claude Code 和 OpenCode 提供网络搜索能力。当 AI 编程代理需要查询实时信息或获取网络内容时，可以通过本项目进行搜索并返回准确答案。

架构概览

用户 → Claude Code（可选子代理）/ OpenCode → MCP Server → Bing 搜索
                                                    ↓
                                Chrome for Testing（页面渲染）

Related MCP server: Kagi MCP Server

运行环境配置

本项目通过 Chrome for Testing 执行搜索和网页渲染。默认可执行文件路径为 D:/app/chrome-win64/chrome.exe；如果 Chrome 安装在其他位置，请在运行 MCP Server 前设置 CHROME_PATH：

# Windows PowerShell（写入当前用户环境变量）
[Environment]::SetEnvironmentVariable("CHROME_PATH", "C:\path\to\chrome.exe", "User")

设置后请重新启动终端以及 Claude Code 或 OpenCode，使新环境变量生效。

# macOS / Linux
export CHROME_PATH="/path/to/chrome"

在 Claude Code 或 OpenCode 中使用

可以将本项目作为 MCP Server 接入 Claude Code 或 OpenCode；Claude Code 用户还可以使用配套的子代理模板。

方式一：作为 MCP Server 使用（Claude Code / OpenCode）

这种方式适用于你想在自己的项目中直接使用搜索工具。

1. 安装依赖

   cd /path/to/local-web-search-agent
   npm install
   npm run build

2. 配置 MCP 客户端

   Claude Code

在项目目录下创建或编辑 .claude/settings.json：

{
  "mcpServers": {
    "local-web-search": {
      "command": "node",
      "args": ["/absolute/path/to/local-web-search-agent/build/index.js"]
    }
  }
}

OpenCode

在项目根目录创建或编辑 opencode.json。如需对所有项目生效，也可以使用全局配置文件 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "local-web-search": {
      "type": "local",
      "command": ["node", "/absolute/path/to/local-web-search-agent/build/index.js"],
      "enabled": true
    }
  }
}

配置后可以检查 MCP Server 状态：

opencode mcp list

3. 使用工具

   配置完成后，你可以在 Claude Code 或 OpenCode 中调用以下工具：

   • web_search_bing: 执行网络搜索

   • read_webpage: 读取网页内容

   • get_current_time: 获取当前时间信息

方式二：作为 Claude Code 子代理使用（推荐）

这种方式会让所有项目都能使用网络搜索能力，更方便。

1. 复制子代理模板

   将 src/agents/local-web-search-agent.md 复制到全局 agents 目录：

   mkdir -p ~/.claude/agents
   cp src/agents/local-web-search-agent.md ~/.claude/agents/

2. 在你的项目中配置 MCP Server

   在你的项目目录下创建或编辑 .claude/settings.json：

   {
     "mcpServers": {
       "local-web-search": {
         "command": "node",
         "args": ["/absolute/path/to/local-web-search-agent/build/index.js"]
       }
     }
   }

3. 使用子代理

   在 Claude Code 中，当需要网络搜索时：

   • 直接提问，让主代理自动判断并调用子代理

   • 或使用 /agent local-web-search-agent 命令明确指定

功能特性

• Bing 搜索: 支持国内版和国际版 Bing 搜索

• 网页内容提取: 自动清洗网页内容，返回干净的 Markdown 格式

• 智能子代理: 自动完成"搜索-阅读-总结"闭环

• 结果缓存: 避免重复抓取同一页面

• 智能搜索技能: 结构化搜索流程，提供多源验证的可靠结果

智能搜索技能 (Smart Search)

本项目提供了一个名为 smart-search 的技能，适用于需要高可靠性和结构化结果的搜索场景。

技能特点

• 多源验证: 自动从多个官方渠道交叉验证信息

• 结构化输出: 提供核心答案、来源链接和可信度评估

• 智能搜索策略: 根据搜索类型自动优化关键词

• 时效性检查: 自动验证信息的发布时间

使用方法

1. 复制技能模板

   将 src/skills/smart-search/SKILL.md 复制到全局 skills 目录：

   mkdir -p ~/.claude/skills/smart-search
   cp src/skills/smart-search/SKILL.md ~/.claude/skills/smart-search/

   注意: Skill 的正确目录结构为 ~/.claude/skills/<skill-name>/SKILL.md

2. 在 Claude Code 中使用

   当需要进行可靠的信息搜索时：

   • 直接提问，让 Claude 自动判断

   • 或使用 /smart-search 命令明确指定

适用场景

输出格式

智能搜索技能会返回结构化的结果，包括：

• 核心信息: 直接回答你的问题

• 信息来源: 多个可信来源的链接和关键信息

• 可信度评估: 官方渠道确认、多源验证、时效性说明

工具说明

web_search_bing

使用 Bing 搜索引擎执行网络搜索。

参数:

• query (string, 必需): 搜索关键词

• num (number, 可选): 返回结果数量，默认 10，最大 50

• useInternational (boolean, 可选): 是否使用 Bing 国际版，默认 false

返回:

[
  {
    "title": "搜索结果标题",
    "url": "https://example.com",
    "snippet": "搜索结果摘要..."
  }
]

read_webpage

访问指定 URL，提取并清洗页面正文内容。

参数:

• url (string, 必需): 要读取的网页 URL

返回:

{
  "title": "网页标题",
  "markdown_content": "# 清洗后的 Markdown 内容"
}

get_current_time

获取当前时间信息，包括当前年份、去年年份、前年年份等。用于搜索最新动态时动态获取年份信息。

参数: 无

返回:

{
  "currentDateTime": "2026/2/26 10:30:00",
  "currentYear": 2026,
  "currentMonth": 2,
  "currentDay": 26,
  "lastYear": 2025,
  "yearBeforeLast": 2024,
  "isoDate": "2026-02-26T02:30:00.000Z"
}

子代理工作流程

local-web-search-agent 子代理会自动执行以下步骤：

1. 分析用户问题，提取核心关键词

2. 使用 web_search_bing 进行搜索

3. 判断最相关的搜索结果

4. 使用 read_webpage 阅读相关页面

5. 整合信息，生成简洁答案

6. 在回答末尾列出引用来源

使用示例

示例 1：查询实时信息

你：Python 最新版本是多少？
→ [主代理自动调用 local-web-search-agent]
→ Python 的最新稳定版本是 3.13.0，发布于 2024 年 10 月。
   来源：https://www.python.org/downloads/

示例 2：复杂查询

你：对比一下最近的两款热门轻薄本，给出选购建议。
→ [子代理进行多轮搜索和阅读]
→ [返回对比表格和购买建议]

项目结构

local-web-search-agent/
├── src/
│   ├── index.ts           # MCP Server 入口
│   ├── agents/
│   │   └── local-web-search-agent.md  # 子代理模板
│   ├── skills/
│   │   └── smart-search/
│   │       └── SKILL.md         # 智能搜索技能
│   └── tools/
│       ├── webSearchBing.ts     # Bing 搜索工具
│       ├── readWebpage.ts       # 网页读取工具
│       ├── currentTime.ts       # 当前时间工具
│       └── cache.ts             # 缓存工具
├── build/                  # 编译输出目录
├── package.json
└── tsconfig.json

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 编译
npm run build

# 监听模式编译
npm run watch

性能优化

缓存机制

• 搜索结果缓存：5 分钟，避免重复搜索

• 网页内容缓存：10 分钟，避免重复抓取

• 自动清理：每分钟自动清理过期缓存

超时控制

• 搜索超时：15 秒，防止搜索卡死

• 页面加载超时：20 秒，防止页面加载过慢

• 页面评估超时：5 秒，防止内容提取卡死

子代理限制

• 最多搜索 10 次

• 最多阅读 30 个页面

• 避免陷入死循环

技术栈

• MCP SDK: Model Context Protocol

• Playwright: 浏览器自动化

• DOMPurify: HTML 清洗

• Turndown: HTML 转 Markdown

• TypeScript: 类型安全

社区扩展 / Forks

本项目主线仅提供本地 Playwright + Bing 搜索路径，强调“本地浏览器 + 人工点击，避免登录外部账号”。
如果你需要基于远程 API 的搜索方案（例如 Tavily），可以使用下面的社区 Fork：

• Tavily-FDE/autopr--fork-web-search-agent
  在本地 Bing 搜索基础上新增 web_search_tavily 工具，使用 Tavily API 进行搜索，需要配置 TAVILY_API_KEY 环境变量。适合需要更快速、稳定的 API 搜索且愿意注册 Tavily 账号的用户。

许可证

MIT