使用说明（Markdown 版）

• 项目简介

  • 这是一个基于 MCP（Model Context Protocol）的服务器实现，提供可对接的工具和资源，帮助 LLM 客户端实现搜索、内容获取与整合渲染等功能。核心能力包括对 Google 自定义搜索 API 的调用、网页内容的读取与提取（Readability 优化），以及将结果以 MCP 工具的形式暴露给客户端使用。

• 主要功能点

  • 通过 MCP Server 暴露工具集，核心工具包括：
    • google_search：快速的 snippet 级搜索，仅返回摘要与链接。
    • deep_search：对顶级结果进行全文内容检索与提取（支持 web、news、images 三种搜索类型），并返回整合内容。
    • deep_search_news：专为新闻检索的便利包装，等同于 deep_search 的新闻模式。
  • 集成 Google Custom Search JSON API，需要 GOOGLE_API_KEY 和 GOOGLE_CX 配置。
  • 使用 Mozilla Readability 进行文章内容提取，提升可读性；在提取失败时回退到简单的 Cheerio 提取。
  • 包含重试机制（指数退避）与并发控制，提升网络请求的鲁棒性与稳定性。
  • 通过 Stdio Server Transport 启动，支持与 MCP 客户端的标准通信。

• 安装步骤（简要）

  • 确保使用 Node.js 18 及以上版本。
  • 获取 Google Custom Search API 的 KEY 与 CX（Programmable Search Engine ID），并设置环境变量 GOOGLE_API_KEY 与 GOOGLE_CX。
  • 安装并运行服务，可以通过 npx 直接使用该 MCP 服务器：
    • 运行方式示例：npx -y @thejusdutt/google-search-mcp
  • 服务器启动后，MCP 客户端即可通过配置连接并调用公开的工具。

• 服务器配置（给 MCP 客户端的连接信息，JSON 格式，包含 server name、command、args 等）

  • 以下信息用于 MCP 客户端配置以连接该 MCP 服务器。请在实际使用中用你自己的 API KEY 与 CX 替换占位符。 { "mcpServers": { "google-search": { "command": "npx", "args": ["-y", "@thejusdutt/google-search-mcp"], "env": { "GOOGLE_API_KEY": "your-google-api-key", "GOOGLE_CX": "your-search-engine-id" } } } }
  • 说明
    • server name 对应 MCP 客户端配置中的服务器名称，此处为 "google-search"。
    • command/args 指定启动 MCP 服务器的命令及参数，示例使用 npx 调用包名为 @thejusdutt/google-search-mcp 的 MCP 服务器。
    • env 包含必需的密钥对：GOOGLE_API_KEY 与 GOOGLE_CX，用于 Google 自定义搜索 API 的认证与定位搜索引擎。

• 基本使用方法

  • 启动后，MCP 客户端通过上述配置与服务器建立连接，并可调用以下工具：
    • 调用 google_search：传入 query、num_results（可选，默认 10），获取搜索结果的链接与摘要。
    • 调用 deep_search：传入 query、num_results、max_content_per_page、search_type 等参数，获取带全文内容的综合结果。
    • 调用 deep_search_news：传入 query、num_results、max_content_per_page，用于新闻主题的全文检索。
  • 客户端收到的响应将包含文本格式化的结果，便于进一步在 LLM 中进行分析、摘要或回答生成。

• 注意事项

  • 运行该服务器需要网络访问 Google Custom Search API，以及对目标网页进行抓取和解析。
  • 内容提取可能受网页结构影响，Readability 为主，若失败将回退到简单文本提取。
  • 根据目标站点的 robots、反爬策略，使用时请遵守相关条款。

• 参考与依赖

  • 使用的 MCP Server 由 @modelcontextprotocol/sdk 提供，采用 Stdio 接受端传输。
  • 依赖 Readability、Cheerio、JSDOM 等用于内容解析的库。