使用说明

MCP网络搜索服务器

一个功能全面的FastAPI MCP（模型上下文协议）服务器，用于谷歌网页搜索，具备完整的搜索功能，包括网页、图片和新闻搜索。

特性/特点

FastAPI 与 MCP 集成所有FastAPI端点均自动作为MCP工具暴露出来
全面搜索通过Google自定义搜索API进行网页、图片和新闻搜索
高级过滤支持时间过滤器、安全搜索、文件类型、图片尺寸等功能
缓存与性能内置缓存，支持TTL（生存时间）和速率限制
**完全符合MCP（可能指某种标准、协议或规范，具体需根据上下文确定）**与任何兼容MCP的AI代理或客户端配合工作
认证就绪支持FastAPI认证机制

建筑学

服务器利用 fastapi-mcp 它会自动将您的FastAPI端点转换为MCP工具，使AI代理无需额外配置即可访问这些端点。

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agent      │───▶│   FastAPI MCP    │───▶│   Google APIs   │
│  (MCP Client)   │    │     Server       │    │  (Custom Search)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │   Cache Layer    │
                        │  (In-Memory)     │
                        └──────────────────┘

安装

克隆并设置环境：

cd /media/phonemt/linux_data/unix_dev/mcp
source .venv/bin/activate

安装依赖项：

uv pip install -r requirements.txt
# Or install from pyproject.toml
uv sync

配置环境：

cp .env.example .env
# Edit .env with your Google API credentials

配置

所需的环境变量

GOOGLE_API_KEY=your_google_api_key_here
GOOGLE_CSE_ID=your_custom_search_engine_id_here

获取API凭证

谷歌自定义搜索API密钥：
- 首选 Google 云控制台
- 创建一个新项目或选择现有项目
- 启用“自定义搜索API”
- 创建凭据（API密钥）
自定义搜索引擎ID:
- 首选谷歌自定义搜索引擎
- 创建一个新的搜索引擎
- 配置以搜索整个网络
- 复制搜索引擎ID

可选设置

DEFAULT_SEARCH_RESULTS=10
MAX_SEARCH_RESULTS=100
CACHE_TTL_SECONDS=3600
RATE_LIMIT_REQUESTS_PER_MINUTE=100
HTTP_TIMEOUT=30
MCP_MOUNT_PATH=/mcp
ENABLE_CORS=true

用法

启动服务器

# Development mode
uvicorn app.main:app --reload --host 0.0.0.0 --port 8500

# Or using the built-in runner
python -m app.main

MCP 集成

服务器自动公开以下MCP工具：

搜索工具

search_web使用高级过滤功能进行网页搜索
search_images带尺寸、类型和颜色过滤器的图像搜索
search_news基于时间过滤的新闻搜索

缓存管理工具

cache_stats获取缓存统计信息
cache_recent查看最近的搜索查询
cache_popular获取最受欢迎的搜索查询
cache_clear清除过期或全部缓存条目

系统工具

health_check服务器健康状态

API 端点

所有端点也作为标准REST API提供：

POST /search/web - 网络搜索
POST /search/images - 图片搜索
POST /search/news - 新闻搜索
GET /cache/stats - 缓存统计信息
GET /cache/recent - 最近的查询
GET /cache/popular - 热门查询
DELETE /cache/clear - 清除缓存
GET /health - 健康检查

示例搜索请求

网页搜索：

{
  \"query\": \"python machine learning\",
  \"num_results\": 10,
  \"site\": \"github.com\",
  \"file_type\": \"pdf\",
  \"time_filter\": \"m\",
  \"safe_search\": \"medium\"
}

图像搜索:

{
  \"query\": \"sunset mountains\",
  \"num_results\": 20,
  \"image_size\": \"large\",
  \"image_type\": \"photo\",
  \"color\": \"orange\"
}

新闻搜索：

{
  \"query\": \"artificial intelligence\",
  \"num_results\": 15,
  \"sort_by\": \"date\",
  \"time_filter\": \"w\"
}

MCP客户端使用情况

将任何兼容MCP的客户端连接到：

HTTP传输： http://localhost:8500/mcp
WebSocket： ws://localhost:8500/mcp （如果已启用）

客户端将自动发现所有可用工具及其架构。

发展

项目结构

app/
├── __init__.py
├── main.py              # FastAPI app and MCP mounting
├── config.py            # Settings and environment config
├── schemas/
│   ├── __init__.py
│   └── search.py        # Pydantic models for requests/responses
├── services/
│   ├── __init__.py
│   ├── google.py        # Google Custom Search API service
│   └── cache.py         # Cache management service
└── mcp_layers/          # Reserved for custom MCP extensions
    ├── __init__.py
    ├── tools.py         # Custom MCP tools (if needed)
    ├── resources.py     # MCP resources
    └── prompts.py       # MCP prompts

添加新的搜索类型

在（某个地方）添加新的枚举 SearchType 在 schemas/search.py
创建请求/响应模型
在（某处）实现搜索逻辑 services/google.py
在（某处）添加端点 main.py
MCP 工具将自动可用！

错误处理

该服务器具备全面的错误处理功能：

使用指数退避的速率限制
API配额管理
错误时的缓存失效处理
优雅降级

部署

Docker

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install uv && uv sync
CMD [\"uvicorn\", \"app.main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8500\"]

生产考量因素

使用基于环境的配置
如需启用，请设置身份验证
根据API配额配置速率限制
建立监控和日志记录
使用生产级的ASGI服务器（uvicorn搭配gunicorn）

许可证

MIT 许可证 - 详见 LICENSE 文件。

贡献；做出贡献

为仓库创建分支（或“克隆仓库”）
创建一个特性分支
进行更改并添加测试
提交拉取请求

支持

对于问题和疑问：

检查一下 FastAPI MCP 文档
审查Google自定义搜索API的限制
在这个仓库中创建一个问题