人工智能MCP 服务【免费下载链接】web-search-mcpA simple, locally hosted Web Search MCP server for use with Local LLMs项目地址https://gitcode.com/gh_mirrors/we/web-search-mcp点击查看免费下载web-search-mcp 是一个运行在本地的网页搜索 MCP 服务器基于 TypeScript 与 MCP SDK 构建无需任何 API 密钥即可为本地 LLM 提供 Bing、Brave、DuckDuckGo 三引擎搜索和网页正文抓取能力。如果你想给本地 AI 助手接入真实的互联网知识又不依赖第三方付费接口这份代码就是非常值得精读的样本。本文带你逐层读懂它的模块分工、多引擎降级策略与浏览器自动化设计 。 项目速览本地网页搜索 MCP 服务器能做什么MCPModel Context Protocol是连接大模型与外部工具的通信协议LM Studio、LibreChat 等本地推理客户端都支持通过它挂载扩展工具。web-search-mcp 就是这个协议下的一个搜索服务器对外暴露 3 个专用工具MCP 工具用途特点full-web-search搜索 抓取完整正文主力工具多引擎 并发提取get-web-search-summaries仅返回结果摘要片段轻量快速适合快速调研get-single-web-page-content提取单个 URL 的正文无需搜索直达内容它的核心卖点在于直连不走 Google Search API 等付费渠道而是用 Playwright 无头浏览器模拟真人访问搜索引擎再用 axios 或浏览器抓取结果页正文——整套流程完全在本地完成。 快速上手3 步搭建本地搜索服务器环境要求Node.js 18、npm 8。# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/we/web-search-mcp cd web-search-mcp # 2. 安装依赖并下载 Playwright 浏览器内核 npm install npx playwright install # 3. 编译 TypeScript 源码 npm run build编译完成后在客户端的mcp.json中指向产物dist/index.js即可{ mcpServers: { web-search: { command: node, args: [/path/to/web-search-mcp/dist/index.js] } } }完整参数说明可查阅项目文档 docs/API.md。️ 源码架构总览核心模块分工一览整个src/目录只有 7 个源文件结构非常清晰按职责可以分成四层文件职责所属层src/index.ts服务器入口注册工具、参数校验、优雅退出MCP 协议层src/search-engine.ts多引擎搜索调度、HTML 解析、质量评分搜索层src/browser-pool.tsPlaywright 浏览器实例池与健康检查资源层src/enhanced-content-extractor.ts网页正文提取axios 浏览器双路提取层src/content-extractor.ts纯 axios 的简化版提取器提取层src/rate-limiter.ts每分钟请求数限流防护层src/types.ts、src/utils.ts类型定义与文本清洗等工具函数基础设施依赖方面见 package.jsonmodelcontextprotocol/sdk提供协议能力playwright负责浏览器自动化axios做高速 HTTP 请求cheerio解析 HTMLzod校验参数p-limit控制并发——每个库都对应一个明确的架构职责没有冗余依赖。 入口文件解读MCP 服务器如何注册 3 个搜索工具入口文件 src/index.ts 中的WebSearchMCPServer类是整个服务器的骨架构造函数里做了两件关键事this.server new McpServer({ name: web-search-mcp, version: 0.3.1 }); this.searchEngine new SearchEngine(); this.contentExtractor new EnhancedContentExtractor();随后setupTools()L30依次注册 3 个工具。值得注意的设计细节zod 参数校验每个工具的参数都用 zod 声明并容忍字符串形式的数字和布尔值L37-L49。因为不同本地模型传参类型不一致这种宽容式校验是兼容各种模型的关键。模型自适应代码会根据参数类型猜模型——发现 Llama 常发字符串参数就自动把正文长度限制到 2000 字符防止大响应把它撑爆L66-L91。通信方式run()使用StdioServerTransportL513-L522即通过标准输入/输出与客户端交换 JSON-RPC 消息这也是 MCP 服务器的标准做法。优雅退出监听SIGINT/SIGTERM信号退出前统一关闭所有浏览器实例避免内存泄漏L472-L511。⚡ 多引擎搜索策略Bing、Brave、DuckDuckGo 的降级原理src/search-engine.ts 是最核心的模块。search()方法把三种搜索途径排成数组按可靠性从高到低依次尝试L36-L40Browser Bing主引擎用 Playwright 启动 Chromium模拟真人打开主页 → 填写搜索框 → 点击搜索的完整流程而不是直接拼 URL以降低被反爬识别的概率Browser Brave备引擎用 Firefox 访问 Brave 搜索同样带重试机制L120-L160Axios DuckDuckGo兜底直接用 HTTP 请求 HTML 版 DuckDuckGo速度最快。每个引擎的 HTML 都由 cheerio 解析且为标题、摘要各准备了一组备选 CSS 选择器——搜索引擎改版时只要其中一组选择器还能命中解析就不会挂掉。更有意思的是质量评分机制assessResultQuality它提取查询词统计每条结果的标题/描述/URL 中的关键词命中率和短语匹配加分再对菜谱、天气、购物等明显跑题的内容做扣分。评分 ≥ 0.8 直接采用低于阈值则继续降级到下一个引擎。这套逻辑让服务器不会搜到就跑而是追求真正相关的结果。 浏览器池设计Playwright 实例管理与健康检查无头浏览器很吃内存src/browser-pool.ts 的BrowserPool类因此承担了资源管家的角色按类型复用用Map缓存 chromium / firefox / webkit 实例超过MAX_BROWSERS默认 3时自动淘汰最旧的L96-L106健康检查每次取用前会新建一个测试 context 再关闭验证浏览器是否还活着不健康就销毁重建L29-L53启动参数隐身带上--disable-blink-featuresAutomationControlled等参数去掉自动化特征。 内容提取从 axios 到无头浏览器的双路策略src/enhanced-content-extractor.ts 是先快后稳的典型实现首选 axiosextractWithAxios毫秒级拿到 HTML失败且判定浏览器能救场时如被反爬拦截、JS 渲染页面自动切换到 Playwright 浏览器提取L33-L61浏览器模式注入隐身脚本覆写navigator.webdriver、伪装 plugins/languages 等指纹L120-L150并拦截图片、字体等无关资源以提速正文清洗用 cheerio 批量移除nav、footer、广告、弹窗等噪声节点再用article/main等优先级选择器锁定正文parseContent。批量抓取时extractContentForResults 用Promise.all并发提取多个页面并给每页套上Promise.race超时保护8 秒单个页面卡死不会拖垮整次搜索失败结果也会返回并标注错误原因供上层汇总。️ 限流器与工具函数稳定运行的细节限流src/rate-limiter.ts 用p-limit限制并发5 路并以每分钟最多 10 次请求为窗口计数超限直接抛错让调用方稍候——避免高频请求把搜索引擎的访问封掉工具函数src/utils.ts 提供文本清洗cleanText、词数统计、随机 User-Agent、isPdfUrl等小函数。主流程会先多要一倍搜索结果、跳过 PDF 链接保证最终交付的条数足够index.ts L373。⚙️ 环境变量速查表自定义你的搜索行为服务器行为可通过环境变量调节在mcp.json的env字段中设置变量默认值作用MAX_CONTENT_LENGTH500000单页最大正文字符数DEFAULT_TIMEOUT6000单次请求超时毫秒MAX_BROWSERS3浏览器实例上限BROWSER_TYPESchromium,firefox启用的浏览器内核RELEVANCE_THRESHOLD0.3结果相关性评分阈值FORCE_MULTI_ENGINE_SEARCHfalse强制尝试全部引擎取最优 内存紧张时把MAX_BROWSERS调成 1追求更快响应可把DEFAULT_TIMEOUT设为 4000。 构建与测试TypeScript 编译与 esbuild 打包日常开发用几条 npm 脚本就够了package.jsonnpm run dev # tsx 热重载模式运行 npm run build # tsc 编译到 dist/ npm run lint # ESLint 检查此外 scripts/bundle.js 用 esbuild 把所有模块打包为单文件dist/bundle.js方便分发给不想装node_modules的用户。tests/目录提供了 test-bing.js、test-brave.js、test-duckduckgo.js 等针对各引擎的独立测试脚本npm run build后可直接运行验证某个引擎是否可用。 总结这套架构值得借鉴的 3 点分层清晰协议层index.ts、搜索层search-engine、资源层browser-pool、提取层extractor各司其职新人 10 分钟就能看懂数据流处处降级引擎降级、请求降级axios → 浏览器、选择器多选一任何单点故障都有后路面向真实模型调优参数宽容校验、按模型自适应截断、质量评分都是为本地 LLM 的不稳定性做的针对性设计。如果你正在用 LM Studio 或 LibreChat 搭建本地 AI 工作流web-search-mcp 是一个零密钥成本就能让模型上网查证的实用方案而其源码结构也是学习 MCP SDK 开发的一手教程。赞分享人工智能MCP 服务【免费下载链接】web-search-mcpA simple, locally hosted Web Search MCP server for use with Local LLMs项目地址https://gitcode.com/gh_mirrors/we/web-search-mcp点击查看免费下载相关推荐MCP stdio 服务器实战基于 TypeScript 与 MCP SDK 构建本地工具服务器MCP stdio 服务器实战基于 TypeScript 与 MCP SDK 构建本地工具服务器 本指南以 mcp for beginners 课程中 05教程文档人工智能mcp-for-beginners 实战用 FastMCP 与 SerpAPI 构建 Web Search MCP 服务器mcp for beginners 实战用 FastMCP 与 SerpAPI 构建 Web Search MCP 服务器 本教程基于 mcp for beg教程文档人工智能better-icons源码解析用TypeScript构建MCP服务器的完整架构better icons源码解析用TypeScript构建MCP服务器的完整架构 better icons 是一个用 TypeScript 构建的图标搜索工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/14 1:04:19 · 阅读 1.2k 读懂 web-search-mcp 源码架构：TypeScript + MCP SDK 构建本地网页搜索服务器的开发指南
人工智能MCP 服务【免费下载链接】web-search-mcpA simple, locally hosted Web Search MCP server for use with Local LLMs项目地址https://gitcode.com/gh_mirrors/we/web-search-mcp点击查看免费下载web-search-mcp 是一个运行在本地的网页搜索 MCP 服务器基于 TypeScript 与 MCP SDK 构建无需任何 API 密钥即可为本地 LLM 提供 Bing、Brave、DuckDuckGo 三引擎搜索和网页正文抓取能力。如果你想给本地 AI 助手接入真实的互联网知识又不依赖第三方付费接口这份代码就是非常值得精读的样本。本文带你逐层读懂它的模块分工、多引擎降级策略与浏览器自动化设计 。 项目速览本地网页搜索 MCP 服务器能做什么MCPModel Context Protocol是连接大模型与外部工具的通信协议LM Studio、LibreChat 等本地推理客户端都支持通过它挂载扩展工具。web-search-mcp 就是这个协议下的一个搜索服务器对外暴露 3 个专用工具MCP 工具用途特点full-web-search搜索 抓取完整正文主力工具多引擎 并发提取get-web-search-summaries仅返回结果摘要片段轻量快速适合快速调研get-single-web-page-content提取单个 URL 的正文无需搜索直达内容它的核心卖点在于直连不走 Google Search API 等付费渠道而是用 Playwright 无头浏览器模拟真人访问搜索引擎再用 axios 或浏览器抓取结果页正文——整套流程完全在本地完成。 快速上手3 步搭建本地搜索服务器环境要求Node.js 18、npm 8。# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/we/web-search-mcp cd web-search-mcp # 2. 安装依赖并下载 Playwright 浏览器内核 npm install npx playwright install # 3. 编译 TypeScript 源码 npm run build编译完成后在客户端的mcp.json中指向产物dist/index.js即可{ mcpServers: { web-search: { command: node, args: [/path/to/web-search-mcp/dist/index.js] } } }完整参数说明可查阅项目文档 docs/API.md。️ 源码架构总览核心模块分工一览整个src/目录只有 7 个源文件结构非常清晰按职责可以分成四层文件职责所属层src/index.ts服务器入口注册工具、参数校验、优雅退出MCP 协议层src/search-engine.ts多引擎搜索调度、HTML 解析、质量评分搜索层src/browser-pool.tsPlaywright 浏览器实例池与健康检查资源层src/enhanced-content-extractor.ts网页正文提取axios 浏览器双路提取层src/content-extractor.ts纯 axios 的简化版提取器提取层src/rate-limiter.ts每分钟请求数限流防护层src/types.ts、src/utils.ts类型定义与文本清洗等工具函数基础设施依赖方面见 package.jsonmodelcontextprotocol/sdk提供协议能力playwright负责浏览器自动化axios做高速 HTTP 请求cheerio解析 HTMLzod校验参数p-limit控制并发——每个库都对应一个明确的架构职责没有冗余依赖。 入口文件解读MCP 服务器如何注册 3 个搜索工具入口文件 src/index.ts 中的WebSearchMCPServer类是整个服务器的骨架构造函数里做了两件关键事this.server new McpServer({ name: web-search-mcp, version: 0.3.1 }); this.searchEngine new SearchEngine(); this.contentExtractor new EnhancedContentExtractor();随后setupTools()L30依次注册 3 个工具。值得注意的设计细节zod 参数校验每个工具的参数都用 zod 声明并容忍字符串形式的数字和布尔值L37-L49。因为不同本地模型传参类型不一致这种宽容式校验是兼容各种模型的关键。模型自适应代码会根据参数类型猜模型——发现 Llama 常发字符串参数就自动把正文长度限制到 2000 字符防止大响应把它撑爆L66-L91。通信方式run()使用StdioServerTransportL513-L522即通过标准输入/输出与客户端交换 JSON-RPC 消息这也是 MCP 服务器的标准做法。优雅退出监听SIGINT/SIGTERM信号退出前统一关闭所有浏览器实例避免内存泄漏L472-L511。⚡ 多引擎搜索策略Bing、Brave、DuckDuckGo 的降级原理src/search-engine.ts 是最核心的模块。search()方法把三种搜索途径排成数组按可靠性从高到低依次尝试L36-L40Browser Bing主引擎用 Playwright 启动 Chromium模拟真人打开主页 → 填写搜索框 → 点击搜索的完整流程而不是直接拼 URL以降低被反爬识别的概率Browser Brave备引擎用 Firefox 访问 Brave 搜索同样带重试机制L120-L160Axios DuckDuckGo兜底直接用 HTTP 请求 HTML 版 DuckDuckGo速度最快。每个引擎的 HTML 都由 cheerio 解析且为标题、摘要各准备了一组备选 CSS 选择器——搜索引擎改版时只要其中一组选择器还能命中解析就不会挂掉。更有意思的是质量评分机制assessResultQuality它提取查询词统计每条结果的标题/描述/URL 中的关键词命中率和短语匹配加分再对菜谱、天气、购物等明显跑题的内容做扣分。评分 ≥ 0.8 直接采用低于阈值则继续降级到下一个引擎。这套逻辑让服务器不会搜到就跑而是追求真正相关的结果。 浏览器池设计Playwright 实例管理与健康检查无头浏览器很吃内存src/browser-pool.ts 的BrowserPool类因此承担了资源管家的角色按类型复用用Map缓存 chromium / firefox / webkit 实例超过MAX_BROWSERS默认 3时自动淘汰最旧的L96-L106健康检查每次取用前会新建一个测试 context 再关闭验证浏览器是否还活着不健康就销毁重建L29-L53启动参数隐身带上--disable-blink-featuresAutomationControlled等参数去掉自动化特征。 内容提取从 axios 到无头浏览器的双路策略src/enhanced-content-extractor.ts 是先快后稳的典型实现首选 axiosextractWithAxios毫秒级拿到 HTML失败且判定浏览器能救场时如被反爬拦截、JS 渲染页面自动切换到 Playwright 浏览器提取L33-L61浏览器模式注入隐身脚本覆写navigator.webdriver、伪装 plugins/languages 等指纹L120-L150并拦截图片、字体等无关资源以提速正文清洗用 cheerio 批量移除nav、footer、广告、弹窗等噪声节点再用article/main等优先级选择器锁定正文parseContent。批量抓取时extractContentForResults 用Promise.all并发提取多个页面并给每页套上Promise.race超时保护8 秒单个页面卡死不会拖垮整次搜索失败结果也会返回并标注错误原因供上层汇总。️ 限流器与工具函数稳定运行的细节限流src/rate-limiter.ts 用p-limit限制并发5 路并以每分钟最多 10 次请求为窗口计数超限直接抛错让调用方稍候——避免高频请求把搜索引擎的访问封掉工具函数src/utils.ts 提供文本清洗cleanText、词数统计、随机 User-Agent、isPdfUrl等小函数。主流程会先多要一倍搜索结果、跳过 PDF 链接保证最终交付的条数足够index.ts L373。⚙️ 环境变量速查表自定义你的搜索行为服务器行为可通过环境变量调节在mcp.json的env字段中设置变量默认值作用MAX_CONTENT_LENGTH500000单页最大正文字符数DEFAULT_TIMEOUT6000单次请求超时毫秒MAX_BROWSERS3浏览器实例上限BROWSER_TYPESchromium,firefox启用的浏览器内核RELEVANCE_THRESHOLD0.3结果相关性评分阈值FORCE_MULTI_ENGINE_SEARCHfalse强制尝试全部引擎取最优 内存紧张时把MAX_BROWSERS调成 1追求更快响应可把DEFAULT_TIMEOUT设为 4000。 构建与测试TypeScript 编译与 esbuild 打包日常开发用几条 npm 脚本就够了package.jsonnpm run dev # tsx 热重载模式运行 npm run build # tsc 编译到 dist/ npm run lint # ESLint 检查此外 scripts/bundle.js 用 esbuild 把所有模块打包为单文件dist/bundle.js方便分发给不想装node_modules的用户。tests/目录提供了 test-bing.js、test-brave.js、test-duckduckgo.js 等针对各引擎的独立测试脚本npm run build后可直接运行验证某个引擎是否可用。 总结这套架构值得借鉴的 3 点分层清晰协议层index.ts、搜索层search-engine、资源层browser-pool、提取层extractor各司其职新人 10 分钟就能看懂数据流处处降级引擎降级、请求降级axios → 浏览器、选择器多选一任何单点故障都有后路面向真实模型调优参数宽容校验、按模型自适应截断、质量评分都是为本地 LLM 的不稳定性做的针对性设计。如果你正在用 LM Studio 或 LibreChat 搭建本地 AI 工作流web-search-mcp 是一个零密钥成本就能让模型上网查证的实用方案而其源码结构也是学习 MCP SDK 开发的一手教程。赞分享人工智能MCP 服务【免费下载链接】web-search-mcpA simple, locally hosted Web Search MCP server for use with Local LLMs项目地址https://gitcode.com/gh_mirrors/we/web-search-mcp点击查看免费下载相关推荐MCP stdio 服务器实战基于 TypeScript 与 MCP SDK 构建本地工具服务器MCP stdio 服务器实战基于 TypeScript 与 MCP SDK 构建本地工具服务器 本指南以 mcp for beginners 课程中 05教程文档人工智能mcp-for-beginners 实战用 FastMCP 与 SerpAPI 构建 Web Search MCP 服务器mcp for beginners 实战用 FastMCP 与 SerpAPI 构建 Web Search MCP 服务器 本教程基于 mcp for beg教程文档人工智能better-icons源码解析用TypeScript构建MCP服务器的完整架构better icons源码解析用TypeScript构建MCP服务器的完整架构 better icons 是一个用 TypeScript 构建的图标搜索工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考