Victor WebSearch MCP - Enterprise-Grade Web Search Service / 高质量 Web 搜索服务

Posted on 八月 12, 2025

Victor WebSearch MCP - Enterprise-Grade Web Search Service

Published: 2025-08-12 | Author: Victor Mustar | Platform: Hugging Face Space | Likes: 133 ⭐

English Documentation

Overview

Victor WebSearch MCP is a production-ready web search server that empowers AI assistants with real-time internet access capabilities. Built on the Gradio MCP framework and powered by Serper API, it provides high-quality search results with intelligent content extraction and structured data formatting.

This server bridges the gap between language models and the dynamic web, enabling AI systems to retrieve, process, and deliver up-to-date information from the internet. Whether you need general web search or real-time news monitoring, Victor WebSearch MCP delivers reliable, rate-limited, and enterprise-ready search functionality.

Key Highlights:

🔍 Dual search modes: General web search and news-specific search
🌐 Powered by Serper API for high-quality search results
📄 Intelligent content extraction using Trafilatura
⚡ Server-Sent Events (SSE) transport for remote access
🛡️ Built-in rate limiting (200 requests/hour)
🚀 Deploy locally or use remote HF Space
🎯 Production-grade reliability with structured output

Architecture & Technology Stack

Core Technologies:

Framework: Gradio MCP - Modern Python framework for MCP server development
Search Engine: Serper API - Google Search API for developers
Content Extraction: Trafilatura - Advanced web content extraction library
HTTP Client: httpx - Modern, async-capable HTTP client
Rate Limiting: limits - Request rate limiting library
Date Processing: python-dateutil - Robust date/time handling

Transport Method:

HTTP Server-Sent Events (SSE) over /gradio_api/mcp/sse endpoint
Stateless, scalable architecture
Compatible with any MCP client supporting SSE transport

Deployment Options:

Remote HF Space (Recommended): Direct SSE connection to hosted service
Local Python Process: Clone and run on your infrastructure
Docker Container: Containerized deployment for production environments

Features

1. Dual Search Modes

General Search Mode (search_type: "search")

Ideal for: Blog posts, documentation, articles, research papers
Broad web coverage across all content types
Comprehensive result ranking by relevance
Full-text content extraction from search results
Use cases: Research, fact-checking, content discovery

News Search Mode (search_type: "news")

Ideal for: Real-time news, breaking stories, current events
Time-sensitive news article prioritization
Publication date and source metadata
Specialized news content extraction
Use cases: News monitoring, trend tracking, real-time updates

2. Intelligent Content Extraction

The server uses Trafilatura, a state-of-the-art web scraping library, to extract clean, structured content from web pages:

Main Content Isolation: Removes navigation, ads, footers, sidebars
Format Preservation: Maintains text structure, paragraphs, and hierarchy
Metadata Extraction: Captures authors, dates, descriptions
Multi-language Support: Works with content in any language
Fallback Handling: Graceful degradation when extraction fails
Performance Optimized: Fast extraction with minimal resource usage

3. Structured Output Format

Every search result returns a consistent, machine-readable structure:

{
  "title": "Article or Page Title",
  "url": "https://example.com/article",
  "snippet": "Brief summary or description from search results",
  "content": "Full extracted text content from the webpage...",
  "metadata": {
    "position": 1,
    "publishedDate": "2025-01-15",
    "source": "example.com"
  }
}

Benefits:

Easy parsing and processing by AI systems
Consistent field names and data types
Comprehensive information for decision-making
Metadata for filtering and sorting

4. Flexible Result Control

Configure the number of results returned per search:

Range: 1-20 results per query
Default: 4 results (optimal for most AI use cases)
Trade-offs: More results = more comprehensive but slower response
Recommendation: Start with 4, increase for research-heavy tasks

5. Rate Limiting Protection

Built-in rate limiting prevents abuse and ensures fair usage:

Limit: 200 requests per hour per client
Purpose: Protects against accidental loops and malicious usage
Behavior: Returns HTTP 429 when limit exceeded
Reset: Rolling 1-hour window
Monitoring: Track usage through response headers

6. Gradio MCP Integration

Leverages Gradio’s MCP capabilities for robust server implementation:

Standard MCP Protocol: Full compliance with MCP specification
Automatic Discovery: Tools exposed via MCP introspection
Error Handling: Structured error responses
Logging: Built-in request/response logging
Hot Reload: Development mode with auto-reload

7. SSE Transport Support

Server-Sent Events provide reliable, scalable remote access:

Stateless: No persistent connections required
Firewall-Friendly: Works over standard HTTP/HTTPS
Real-time: Immediate response delivery
Compatible: Works with all major MCP clients
Remote-First: Designed for cloud deployment

Tools & API Reference

Tool: `search_web`

Description: Performs web search and returns structured results with full content extraction.

Parameters:

Parameter	Type	Required	Default	Description
`query`	string	Yes	-	Search query string. Supports natural language and advanced search operators.
`num_results`	integer	No	4	Number of results to return. Valid range: 1-20.
`search_type`	string	No	“search”	Search mode: “search” for general web search, “news” for news articles.

Return Value:

Array of search result objects:

[
  {
    "title": "string",
    "url": "string",
    "snippet": "string",
    "content": "string",
    "metadata": {
      "position": "integer",
      "publishedDate": "string (ISO 8601)",
      "source": "string"
    }
  }
]

Error Responses:

Error	HTTP Code	Description
`INVALID_QUERY`	400	Empty or malformed query string
`INVALID_NUM_RESULTS`	400	num_results outside 1-20 range
`INVALID_SEARCH_TYPE`	400	search_type not “search” or “news”
`RATE_LIMIT_EXCEEDED`	429	More than 200 requests in 1 hour
`SERPER_API_ERROR`	502	Upstream Serper API failure
`EXTRACTION_FAILED`	500	Content extraction error

Usage Examples:

# General web search with default settings
search_web(query="Python async programming best practices")

# News search with more results
search_web(
    query="artificial intelligence breakthroughs 2025",
    num_results=10,
    search_type="news"
)

# Targeted search with minimal results
search_web(
    query="MCP protocol specification",
    num_results=3,
    search_type="search"
)

Installation & Configuration

Prerequisites

Python: 3.8 or higher
Serper API Key: Sign up at serper.dev (free tier available)
MCP Client: Claude Desktop, VS Code with MCP extension, Cursor, Cline, or any MCP-compatible client

Option 1: Remote HF Space (Recommended)

The simplest deployment method - no local installation required.

Step 1: Configure MCP Client

Add to your MCP client configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "web-search": {
      "type": "sse",
      "url": "https://victor-websearch.hf.space/gradio_api/mcp/sse"
    }
  }
}

Step 2: Restart MCP Client

That’s it! The server is hosted on Hugging Face and ready to use.

Advantages:

Zero local setup
Always up-to-date
No maintenance required
High availability
Automatic scaling

Considerations:

Requires internet connection
Shared rate limits with other users
Public HF Space availability dependent

Option 2: Local Python Process

For full control and private deployment.

Step 1: Clone Repository

1 2	git clone https://huggingface.co/spaces/victor/websearch cd websearch

Step 2: Install Dependencies

# Option A: Use requirements.txt
pip install -r requirements.txt

# Option B: Manual installation
pip install 'gradio[mcp]' httpx trafilatura python-dateutil limits

Step 3: Configure Environment

1	export SERPER_API_KEY='your-serper-api-key-here'

Step 4: Run Server

1	python app_mcp.py

Step 5: Configure MCP Client

{
  "mcpServers": {
    "web-search": {
      "command": "python",
      "args": ["/absolute/path/to/websearch/app_mcp.py"],
      "env": {
        "SERPER_API_KEY": "your-serper-api-key-here"
      }
    }
  }
}

Advantages:

Full control over server
Private API key usage
Custom rate limits
Local network access
Debug capabilities

Option 3: Docker Deployment

For production environments.

Create Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app_mcp.py .

ENV SERPER_API_KEY=""
ENV PORT=7860

EXPOSE 7860

CMD ["python", "app_mcp.py"]

Build and Run:

1 2	docker build -t victor-websearch . docker run -p 7860:7860 -e SERPER_API_KEY='your-key' victor-websearch

Configure MCP Client:

{
  "mcpServers": {
    "web-search": {
      "type": "sse",
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

Use Cases

1. AI Real-Time Information Queries

Enable AI assistants to access current information beyond their training data cutoff.

Scenario: User asks “What are the latest developments in quantum computing?”

Flow:

AI recognizes need for current information
Calls search_web(query="quantum computing latest developments 2025", search_type="news")
Receives recent articles with full content
Synthesizes information into comprehensive answer
Cites sources from search results

Benefits: AI provides accurate, up-to-date responses with source attribution.

2. News Monitoring & Alerting

Track specific topics and receive real-time updates.

Scenario: Monitor competitor announcements

Implementation:

def monitor_competitor(company_name):
    results = search_web(
        query=f"{company_name} announcement OR launch OR release",
        search_type="news",
        num_results=10
    )
    return filter_new_articles(results)

Benefits: Automated competitor intelligence gathering.

3. Research Assistance

Accelerate research by quickly finding and extracting relevant content.

Scenario: Literature review for academic paper

Implementation:

def research_topic(topic, num_sources=20):
    results = search_web(
        query=f"{topic} research paper OR study OR analysis",
        num_results=num_sources,
        search_type="search"
    )
    return extract_citations_and_summaries(results)

Benefits: Rapid source discovery with full-text access.

4. Content Aggregation

Collect information from multiple sources for comprehensive analysis.

Scenario: Market research report generation

Implementation:

def aggregate_market_insights(market):
    searches = [
        f"{market} market size 2025",
        f"{market} industry trends",
        f"{market} key players"
    ]
    all_results = []
    for query in searches:
        all_results.extend(search_web(query=query, num_results=5))
    return synthesize_report(all_results)

Benefits: Multi-source data compilation for informed decision-making.

5. Fact-Checking

Verify AI-generated content against current web sources.

Scenario: Validate statistical claims

Implementation:

def fact_check(claim):
    results = search_web(
        query=f'"{claim}" statistics data',
        num_results=3,
        search_type="search"
    )
    return verify_against_sources(claim, results)

Benefits: Improved accuracy and trustworthiness of AI outputs.

6. Competitive Intelligence

Monitor and analyze competitor activities through public information.

Scenario: Track competitor product launches

Implementation:

def competitor_analysis(competitors):
    insights = {}
    for competitor in competitors:
        results = search_web(
            query=f"{competitor} new product OR feature OR update",
            search_type="news",
            num_results=8
        )
        insights[competitor] = analyze_activities(results)
    return insights

Benefits: Systematic competitor monitoring and strategic insights.

Best Practices

Query Optimization

Do’s:

Use specific, descriptive search terms
Include relevant keywords and context
Use quotes for exact phrases
Add date/time qualifiers when needed
Specify content type (guide, tutorial, review)

Don’ts:

Avoid overly broad single-word queries
Don’t use excessive boolean operators (handled by Serper)
Avoid special characters unless necessary
Don’t include meta-instructions in query

Examples:

Good: "Python asyncio" tutorial beginners 2025
Bad: python

Good: climate change impact coastal cities research
Bad: climate

Result Count Selection

Use Case	Recommended Count	Rationale
Quick fact lookup	1-3	Fastest response, focused results
General Q&A	4-6	Balanced coverage and speed
Research	10-15	Comprehensive source gathering
Monitoring	15-20	Maximum coverage for tracking

Search Type Selection

Content Type	Use “search”	Use “news”
Documentation	✓	✗
Blog posts	✓	~
Breaking news	✗	✓
Current events	~	✓
Research papers	✓	✗
Product reviews	✓	~
Financial updates	~	✓

Rate Limit Management

Strategies:

Cache Results: Store search results locally to reduce repeated queries
Batch Queries: Combine related searches when possible
Prioritize: Focus on high-value queries first
Monitor Usage: Track API calls to avoid hitting limits
Implement Backoff: Retry with exponential backoff on 429 errors

Example Caching:

from functools import lru_cache
import time

@lru_cache(maxsize=100)
def cached_search(query, num_results=4, search_type="search"):
    return search_web(
        query=query,
        num_results=num_results,
        search_type=search_type
    )

Error Handling

Robust Implementation:

def safe_search(query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return search_web(query=query)
        except RateLimitError:
            if attempt < max_retries - 1:
                time.sleep(3600 / 200)  # Wait based on rate limit
            else:
                raise
        except APIError as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                log_error(e)
                return fallback_results(query)

Troubleshooting

Connection Issues

Symptom: Cannot connect to MCP server

Solutions:

Verify SSE URL is correct and accessible
Check firewall/proxy settings
Ensure MCP client supports SSE transport
Test endpoint manually: curl https://victor-websearch.hf.space/gradio_api/mcp/sse
Check HF Space status (for remote deployment)

API Key Problems

Symptom: SERPER_API_ERROR or authentication failures

Solutions:

Verify Serper API key is valid
Check API key has not exceeded quota
Ensure environment variable is set correctly
Test API key directly: curl -X POST https://google.serper.dev/search -H "X-API-KEY: your-key" -d '{"q":"test"}'
Regenerate API key if compromised

Rate Limiting

Symptom: HTTP 429 responses

Solutions:

Reduce query frequency
Implement caching layer
Use exponential backoff
Consider deploying private instance
Upgrade Serper API plan for higher limits

Content Extraction Failures

Symptom: Empty or partial content in results

Solutions:

Some websites block automated access
JavaScript-heavy sites may not extract well
Check if site has robots.txt restrictions
Fall back to snippet when content is empty
Consider alternative sources for problematic domains

Performance Issues

Symptom: Slow response times

Solutions:

Reduce num_results parameter
Use general search instead of news for faster results
Check network latency to HF Space
Consider local deployment for lower latency
Implement parallel search for multiple queries

Security Considerations

API Key Protection

Never commit API keys to version control
Use environment variables for key storage
Implement key rotation policies
Monitor API usage for anomalies
Use separate keys for development and production

Rate Limiting

Protects against accidental loops in AI systems
Prevents resource exhaustion attacks
Ensures fair usage across clients
Enforces cost control for API usage

Data Privacy

Search queries and results pass through Serper API
No persistent storage of search data by default
Consider local deployment for sensitive queries
Review Serper API privacy policy for compliance
Implement query logging controls as needed

Content Validation

Verify sources before trusting content
Implement malicious content filtering
Check SSL certificates of extracted sites
Sanitize HTML/script from extracted content
Validate URL schemes (http/https only)

Performance Metrics

Typical Response Times (from remote HF Space):

Simple search (4 results): 2-4 seconds
News search (10 results): 4-6 seconds
High result count (20 results): 6-10 seconds

Factors Affecting Performance:

Number of results requested
Content extraction complexity
Network latency to HF Space
Serper API response time
Target website response time

Optimization Tips:

Start with fewer results and increase as needed
Use local deployment for lowest latency
Implement result caching
Parallelize independent searches
Pre-fetch for predictable queries

FAQ

Q: Do I need my own Serper API key?
A: For local deployment, yes. For remote HF Space, the hosted instance includes API access (shared rate limits).

Q: What’s the difference between this and native web search tools?
A: Victor WebSearch provides structured output, content extraction, and MCP integration specifically designed for AI systems.

Q: Can I use this in production?
A: Yes, with proper rate limiting, error handling, and monitoring. Consider local deployment for production workloads.

Q: Does it work with Claude Desktop?
A: Yes, fully compatible with Claude Desktop and all MCP clients supporting SSE transport.

Q: How many languages does it support?
A: Serper API supports all languages. Trafilatura content extraction works with 200+ languages.

Q: Can I filter results by date?
A: Add date qualifiers to your query (e.g., “after:2025-01-01”) or use news search for recent content.

Q: Is the extracted content copyrighted?
A: Yes, respect copyright and terms of service of source websites. Use content according to fair use principles.

Q: Can I increase the rate limit?
A: For remote HF Space, limits are shared. Deploy locally with your own Serper API key for dedicated limits.

Q: Does it support advanced search operators?
A: Yes, Serper API supports Google search operators (site:, intitle:, filetype:, etc.).

Q: How fresh is the news search?
A: News search returns articles from the last 24-48 hours by default. Serper API updates in near real-time.

Compatibility

MCP SDK Version: Gradio MCP framework (compatible with MCP protocol v1.0+)

Supported MCP Clients:

Claude Desktop (macOS and Windows)
VS Code with MCP extension
Cursor IDE
Cline
Continue
Any client supporting MCP over SSE transport

Transport Methods: Server-Sent Events (SSE) over HTTP/HTTPS

Platform: Hugging Face Space (cloud-hosted) or self-hosted

Python Requirements: Python 3.8, 3.9, 3.10, 3.11, 3.12

Links & Resources

Hugging Face Space: https://huggingface.co/spaces/victor/websearch
Serper API: https://serper.dev
Trafilatura Docs: https://trafilatura.readthedocs.io
Gradio MCP: https://www.gradio.app/guides/creating-a-gradio-mcp-server
MCP Protocol: https://modelcontextprotocol.io

中文文档

概述

Victor WebSearch MCP 是一个生产级的网页搜索服务器，为 AI 助手提供实时互联网访问能力。该服务基于 Gradio MCP 框架构建，由 Serper API 提供支持，提供高质量的搜索结果、智能内容提取和结构化数据格式化。

该服务器在语言模型与动态网络之间架起了桥梁，使 AI 系统能够从互联网检索、处理并交付最新信息。无论您需要通用网页搜索还是实时新闻监控，Victor WebSearch MCP 都能提供可靠、限速且企业就绪的搜索功能。

核心亮点：

🔍 双搜索模式：通用网页搜索和新闻专项搜索
🌐 由 Serper API 提供支持，确保高质量搜索结果
📄 使用 Trafilatura 进行智能内容提取
⚡ 支持服务器发送事件（SSE）传输，方便远程访问
🛡️ 内置速率限制（每小时 200 次请求）
🚀 支持本地部署或使用远程 HF Space
🎯 生产级可靠性，结构化输出

架构与技术栈

核心技术：

框架: Gradio MCP - 用于 MCP 服务器开发的现代 Python 框架
搜索引擎: Serper API - 面向开发者的 Google 搜索 API
内容提取: Trafilatura - 先进的网页内容提取库
HTTP 客户端: httpx - 现代、支持异步的 HTTP 客户端
速率限制: limits - 请求速率限制库
日期处理: python-dateutil - 强大的日期/时间处理

传输方式：

通过 /gradio_api/mcp/sse 端点的 HTTP 服务器发送事件（SSE）
无状态、可扩展架构
与任何支持 SSE 传输的 MCP 客户端兼容

部署选项：

远程 HF Space（推荐）：直接 SSE 连接到托管服务
本地 Python 进程：在您的基础设施上克隆并运行
Docker 容器：用于生产环境的容器化部署

功能特性

1. 双搜索模式

通用搜索模式 (search_type: "search")

适用于：博客文章、文档、文章、研究论文
覆盖所有内容类型的广泛网页
按相关性进行全面排序
从搜索结果中提取全文内容
使用场景：研究、事实核查、内容发现

新闻搜索模式 (search_type: "news")

适用于：实时新闻、突发新闻、当前事件
时间敏感的新闻文章优先级排序
包含发布日期和来源元数据
专门的新闻内容提取
使用场景：新闻监控、趋势跟踪、实时更新

2. 智能内容提取

该服务器使用 Trafilatura（一个最先进的网页抓取库）从网页中提取干净、结构化的内容：

主内容隔离：删除导航、广告、页脚、侧边栏
格式保留：保持文本结构、段落和层次结构
元数据提取：捕获作者、日期、描述
多语言支持：适用于任何语言的内容
回退处理：提取失败时优雅降级
性能优化：快速提取，最小资源使用

3. 结构化输出格式

每个搜索结果返回一致的、机器可读的结构：

{
  "title": "文章或页面标题",
  "url": "https://example.com/article",
  "snippet": "来自搜索结果的简要摘要或描述",
  "content": "从网页提取的完整文本内容...",
  "metadata": {
    "position": 1,
    "publishedDate": "2025-01-15",
    "source": "example.com"
  }
}

优势：

AI 系统易于解析和处理
一致的字段名称和数据类型
为决策提供全面的信息
用于过滤和排序的元数据

4. 灵活的结果控制

配置每次搜索返回的结果数量：

范围：每次查询 1-20 个结果
默认值：4 个结果（对大多数 AI 使用场景最优）
权衡：更多结果 = 更全面但响应更慢
建议：从 4 个开始，对研究密集型任务增加

5. 速率限制保护

内置速率限制防止滥用并确保公平使用：

限制：每个客户端每小时 200 次请求
目的：防止意外循环和恶意使用
行为：超过限制时返回 HTTP 429
重置：滚动 1 小时窗口
监控：通过响应头跟踪使用情况

6. Gradio MCP 集成

利用 Gradio 的 MCP 功能实现强大的服务器实现：

标准 MCP 协议：完全符合 MCP 规范
自动发现：通过 MCP 内省公开工具
错误处理：结构化错误响应
日志记录：内置请求/响应日志记录
热重载：开发模式下自动重载

7. SSE 传输支持

服务器发送事件提供可靠、可扩展的远程访问：

无状态：不需要持久连接
防火墙友好：通过标准 HTTP/HTTPS 工作
实时：立即交付响应
兼容：与所有主流 MCP 客户端兼容
远程优先：专为云部署设计

工具与 API 参考

工具：`search_web`

描述：执行网页搜索并返回带有完整内容提取的结构化结果。

参数：

参数	类型	必需	默认值	描述
`query`	string	是	-	搜索查询字符串。支持自然语言和高级搜索运算符。
`num_results`	integer	否	4	要返回的结果数量。有效范围：1-20。
`search_type`	string	否	“search”	搜索模式：”search” 用于通用网页搜索，”news” 用于新闻文章。

返回值：

搜索结果对象数组：

[
  {
    "title": "string",
    "url": "string",
    "snippet": "string",
    "content": "string",
    "metadata": {
      "position": "integer",
      "publishedDate": "string (ISO 8601)",
      "source": "string"
    }
  }
]

错误响应：

错误	HTTP 代码	描述
`INVALID_QUERY`	400	空或格式错误的查询字符串
`INVALID_NUM_RESULTS`	400	num_results 超出 1-20 范围
`INVALID_SEARCH_TYPE`	400	search_type 不是 “search” 或 “news”
`RATE_LIMIT_EXCEEDED`	429	1 小时内超过 200 次请求
`SERPER_API_ERROR`	502	上游 Serper API 故障
`EXTRACTION_FAILED`	500	内容提取错误

使用示例：

# 使用默认设置进行通用网页搜索
search_web(query="Python 异步编程最佳实践")

# 使用更多结果进行新闻搜索
search_web(
    query="2025年人工智能突破",
    num_results=10,
    search_type="news"
)

# 使用最少结果进行针对性搜索
search_web(
    query="MCP 协议规范",
    num_results=3,
    search_type="search"
)

安装与配置

前置要求

Python：3.8 或更高版本
Serper API 密钥：在 serper.dev 注册（有免费层级）
MCP 客户端：Claude Desktop、带 MCP 扩展的 VS Code、Cursor、Cline 或任何兼容 MCP 的客户端

选项 1：远程 HF Space（推荐）

最简单的部署方法 - 无需本地安装。

步骤 1：配置 MCP 客户端

添加到您的 MCP 客户端配置（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "web-search": {
      "type": "sse",
      "url": "https://victor-websearch.hf.space/gradio_api/mcp/sse"
    }
  }
}

步骤 2：重启 MCP 客户端

就是这样！服务器托管在 Hugging Face 上，随时可用。

优势：

零本地设置
始终保持最新
无需维护
高可用性
自动扩展

注意事项：

需要互联网连接
与其他用户共享速率限制
依赖于公共 HF Space 的可用性

选项 2：本地 Python 进程

用于完全控制和私有部署。

步骤 1：克隆仓库

1 2	git clone https://huggingface.co/spaces/victor/websearch cd websearch

步骤 2：安装依赖

# 选项 A：使用 requirements.txt
pip install -r requirements.txt

# 选项 B：手动安装
pip install 'gradio[mcp]' httpx trafilatura python-dateutil limits

步骤 3：配置环境

1	export SERPER_API_KEY='your-serper-api-key-here'

步骤 4：运行服务器

1	python app_mcp.py

步骤 5：配置 MCP 客户端

{
  "mcpServers": {
    "web-search": {
      "command": "python",
      "args": ["/absolute/path/to/websearch/app_mcp.py"],
      "env": {
        "SERPER_API_KEY": "your-serper-api-key-here"
      }
    }
  }
}

优势：

完全控制服务器
私有 API 密钥使用
自定义速率限制
本地网络访问
调试能力

选项 3：Docker 部署

用于生产环境。

创建 Dockerfile：

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app_mcp.py .

ENV SERPER_API_KEY=""
ENV PORT=7860

EXPOSE 7860

CMD ["python", "app_mcp.py"]

构建和运行：

1 2	docker build -t victor-websearch . docker run -p 7860:7860 -e SERPER_API_KEY='your-key' victor-websearch

配置 MCP 客户端：

{
  "mcpServers": {
    "web-search": {
      "type": "sse",
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

使用场景

1. AI 实时信息查询

使 AI 助手能够访问超出其训练数据截止日期的当前信息。

场景：用户询问”量子计算的最新进展是什么？”

流程：

AI 识别需要当前信息
调用 search_web(query="量子计算最新进展 2025", search_type="news")
接收包含完整内容的最新文章
将信息综合成全面的答案
引用搜索结果中的来源

优势：AI 提供准确、最新的响应，并附有来源说明。

2. 新闻监控与警报

跟踪特定主题并接收实时更新。

场景：监控竞争对手公告

实现：

def monitor_competitor(company_name):
    results = search_web(
        query=f"{company_name} 公告 OR 发布 OR 推出",
        search_type="news",
        num_results=10
    )
    return filter_new_articles(results)

优势：自动化竞争对手情报收集。

3. 研究辅助

通过快速查找和提取相关内容加速研究。

场景：学术论文的文献综述

实现：

def research_topic(topic, num_sources=20):
    results = search_web(
        query=f"{topic} 研究论文 OR 研究 OR 分析",
        num_results=num_sources,
        search_type="search"
    )
    return extract_citations_and_summaries(results)

优势：快速发现来源并获得全文访问。

4. 内容聚合

从多个来源收集信息以进行综合分析。

场景：市场研究报告生成

实现：

def aggregate_market_insights(market):
    searches = [
        f"{market} 市场规模 2025",
        f"{market} 行业趋势",
        f"{market} 主要参与者"
    ]
    all_results = []
    for query in searches:
        all_results.extend(search_web(query=query, num_results=5))
    return synthesize_report(all_results)

优势：多来源数据汇编，用于明智决策。

5. 事实核查

根据当前网络来源验证 AI 生成的内容。

场景：验证统计声明

实现：

def fact_check(claim):
    results = search_web(
        query=f'"{claim}" 统计 数据',
        num_results=3,
        search_type="search"
    )
    return verify_against_sources(claim, results)

优势：提高 AI 输出的准确性和可信度。

6. 竞争情报

通过公开信息监控和分析竞争对手活动。

场景：跟踪竞争对手产品发布

实现：

def competitor_analysis(competitors):
    insights = {}
    for competitor in competitors:
        results = search_web(
            query=f"{competitor} 新产品 OR 功能 OR 更新",
            search_type="news",
            num_results=8
        )
        insights[competitor] = analyze_activities(results)
    return insights

优势：系统性竞争对手监控和战略洞察。

最佳实践

查询优化

应该做的：

使用具体、描述性的搜索词
包含相关的关键词和上下文
对精确短语使用引号
需要时添加日期/时间限定符
指定内容类型（指南、教程、评论）

不应该做的：

避免过于宽泛的单词查询
不要使用过多的布尔运算符（由 Serper 处理）
除非必要，避免特殊字符
不要在查询中包含元指令

示例：

好："Python asyncio" 教程初学者 2025
不好：python

好：气候变化影响沿海城市研究
不好：气候

结果数量选择

使用场景	推荐数量	理由
快速事实查找	1-3	最快响应，集中结果
一般问答	4-6	平衡覆盖范围和速度
研究	10-15	全面的来源收集
监控	15-20	跟踪的最大覆盖范围

搜索类型选择

内容类型	使用 “search”	使用 “news”
文档	✓	✗
博客文章	✓	~
突发新闻	✗	✓
当前事件	~	✓
研究论文	✓	✗
产品评论	✓	~
财务更新	~	✓

速率限制管理

策略：

缓存结果：本地存储搜索结果以减少重复查询
批量查询：尽可能合并相关搜索
优先级排序：首先关注高价值查询
监控使用情况：跟踪 API 调用以避免达到限制
实施退避：在 429 错误时使用指数退避重试

缓存示例：

from functools import lru_cache
import time

@lru_cache(maxsize=100)
def cached_search(query, num_results=4, search_type="search"):
    return search_web(
        query=query,
        num_results=num_results,
        search_type=search_type
    )

错误处理

健壮的实现：

def safe_search(query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return search_web(query=query)
        except RateLimitError:
            if attempt < max_retries - 1:
                time.sleep(3600 / 200)  # 根据速率限制等待
            else:
                raise
        except APIError as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # 指数退避
            else:
                log_error(e)
                return fallback_results(query)

故障排除

连接问题

症状：无法连接到 MCP 服务器

解决方案：

验证 SSE URL 是否正确且可访问
检查防火墙/代理设置
确保 MCP 客户端支持 SSE 传输
手动测试端点：curl https://victor-websearch.hf.space/gradio_api/mcp/sse
检查 HF Space 状态（用于远程部署）

API 密钥问题

症状：SERPER_API_ERROR 或认证失败

解决方案：

验证 Serper API 密钥是否有效
检查 API 密钥是否超过配额
确保环境变量设置正确
直接测试 API 密钥：curl -X POST https://google.serper.dev/search -H "X-API-KEY: your-key" -d '{"q":"test"}'
如果密钥泄露，重新生成

速率限制

症状：HTTP 429 响应

解决方案：

降低查询频率
实施缓存层
使用指数退避
考虑部署私有实例
升级 Serper API 计划以获得更高限制

内容提取失败

症状：结果中内容为空或部分

解决方案：

某些网站阻止自动访问
JavaScript 密集型网站可能提取效果不佳
检查网站是否有 robots.txt 限制
当内容为空时回退到摘要
考虑为问题域名使用替代来源

性能问题

症状：响应时间慢

解决方案：

减少 num_results 参数
使用通用搜索而不是新闻搜索以获得更快结果
检查到 HF Space 的网络延迟
考虑本地部署以降低延迟
为多个查询实施并行搜索

安全考虑

API 密钥保护

永远不要提交 API 密钥到版本控制
使用环境变量存储密钥
实施密钥轮换策略
监控 API 使用情况的异常
为开发和生产使用单独的密钥

速率限制

防止 AI 系统中的意外循环
防止资源耗尽攻击
确保客户端之间的公平使用
强制执行 API 使用的成本控制

数据隐私

搜索查询和结果通过 Serper API
默认情况下不持久存储搜索数据
对敏感查询考虑本地部署
查看 Serper API 隐私政策以确保合规
根据需要实施查询日志记录控制

内容验证

在信任内容之前验证来源
实施恶意内容过滤
检查提取网站的 SSL 证书
清理提取内容中的 HTML/脚本
验证 URL 方案（仅 http/https）

性能指标

典型响应时间（从远程 HF Space）：

简单搜索（4 个结果）：2-4 秒
新闻搜索（10 个结果）：4-6 秒
高结果数量（20 个结果）：6-10 秒

影响性能的因素：

请求的结果数量
内容提取复杂度
到 HF Space 的网络延迟
Serper API 响应时间
目标网站响应时间

优化提示：

从较少的结果开始，根据需要增加
使用本地部署以获得最低延迟
实施结果缓存
并行化独立搜索
为可预测的查询预取

常见问题

问：我需要自己的 Serper API 密钥吗？
答：对于本地部署，是的。对于远程 HF Space，托管实例包含 API 访问（共享速率限制）。

问：这与原生网页搜索工具有什么区别？
答：Victor WebSearch 提供结构化输出、内容提取和专为 AI 系统设计的 MCP 集成。

问：我可以在生产环境中使用吗？
答：可以，前提是有适当的速率限制、错误处理和监控。对于生产工作负载，考虑本地部署。

问：它与 Claude Desktop 兼容吗？
答：是的，与 Claude Desktop 和所有支持 SSE 传输的 MCP 客户端完全兼容。

问：它支持多少种语言？
答：Serper API 支持所有语言。Trafilatura 内容提取适用于 200+ 种语言。

问：我可以按日期过滤结果吗？
答：在查询中添加日期限定符（例如”after:2025-01-01”）或使用新闻搜索获取最新内容。

问：提取的内容是否受版权保护？
答：是的，尊重来源网站的版权和服务条款。根据合理使用原则使用内容。

问：我可以提高速率限制吗？
答：对于远程 HF Space，限制是共享的。使用您自己的 Serper API 密钥本地部署可获得专用限制。

问：它支持高级搜索运算符吗？
答：是的，Serper API 支持 Google 搜索运算符（site:、intitle:、filetype: 等）。

问：新闻搜索的时效性如何？
答：新闻搜索默认返回过去 24-48 小时的文章。Serper API 近乎实时更新。

兼容性

MCP SDK 版本：Gradio MCP 框架（与 MCP 协议 v1.0+ 兼容）

支持的 MCP 客户端：

Claude Desktop（macOS 和 Windows）
带 MCP 扩展的 VS Code
Cursor IDE
Cline
Continue
任何支持 MCP over SSE 传输的客户端

传输方式：通过 HTTP/HTTPS 的服务器发送事件（SSE）

平台：Hugging Face Space（云托管）或自托管

Python 要求：Python 3.8、3.9、3.10、3.11、3.12

链接与资源

Hugging Face Space：https://huggingface.co/spaces/victor/websearch
Serper API：https://serper.dev
Trafilatura 文档：https://trafilatura.readthedocs.io
Gradio MCP：https://www.gradio.app/guides/creating-a-gradio-mcp-server
MCP 协议：https://modelcontextprotocol.io

Victor WebSearch MCP - Enterprise-Grade Web Search Service

English Documentation

Overview

Architecture & Technology Stack

Features

1. Dual Search Modes

2. Intelligent Content Extraction

3. Structured Output Format

4. Flexible Result Control

5. Rate Limiting Protection

6. Gradio MCP Integration

7. SSE Transport Support

Tools & API Reference

Tool: search_web

Installation & Configuration

Prerequisites

Option 1: Remote HF Space (Recommended)

Option 2: Local Python Process

Option 3: Docker Deployment

Use Cases

1. AI Real-Time Information Queries

2. News Monitoring & Alerting

3. Research Assistance

4. Content Aggregation

5. Fact-Checking

6. Competitive Intelligence

Best Practices

Query Optimization

Result Count Selection

Search Type Selection

Rate Limit Management

Error Handling

Troubleshooting

Connection Issues

API Key Problems

Rate Limiting

Content Extraction Failures

Performance Issues

Security Considerations

API Key Protection

Rate Limiting

Data Privacy

Content Validation

Performance Metrics

FAQ

Compatibility

Links & Resources

中文文档

概述

架构与技术栈

功能特性

1. 双搜索模式

2. 智能内容提取

3. 结构化输出格式

4. 灵活的结果控制

5. 速率限制保护

6. Gradio MCP 集成

7. SSE 传输支持

工具与 API 参考

工具：search_web

安装与配置

前置要求

选项 1：远程 HF Space（推荐）

选项 2：本地 Python 进程

选项 3：Docker 部署

使用场景

1. AI 实时信息查询

2. 新闻监控与警报

3. 研究辅助

4. 内容聚合

5. 事实核查

6. 竞争情报

最佳实践

查询优化

结果数量选择

搜索类型选择

速率限制管理

错误处理

故障排除

连接问题

Tool: `search_web`

工具：`search_web`