bocha-mcp

aweffr/bocha-mcp

3.2

If you are the rightful owner of bocha-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Web Search MCP Server is designed to provide a standardized interface for AI applications to access high-quality web search capabilities using the Model Context Protocol (MCP).

Tools
2
Resources
0
Prompts
0

Web Search MCP Server (博查AI版本)

Python FastAPI MCP License: MIT

📋 项目背景与需求

🎯 项目起源

本项目旨在实现一个基于 Model Context Protocol (MCP) 的网络搜索服务器，将博查AI的强大搜索能力通过标准化的 MCP 接口暴露给 AI 应用。

🚀 核心需求

  • 标准化接口: 使用 MCP 协议，确保与各种 AI 应用和 LLM 的兼容性
  • 高质量搜索: 集成博查AI Web Search API，提供准确、全面的搜索结果
  • 安全认证: 通过 Bearer token 实现安全的访问控制
  • 灵活部署: 支持 streamable HTTP 传输，便于集成和部署
  • 生产就绪: 完善的错误处理、日志记录和监控功能

🛠️ 技术选型

  • 框架: FastAPI + FastMCP - 现代、高性能的 Web 框架
  • 搜索: 博查AI Web Search API - 高质量的中文搜索服务
  • 传输: Streamable HTTP - 支持 SSE 流式传输
  • 认证: Bearer Token - 简单安全的认证机制

✨ 功能特性

  • 🔍 集成博查AI Web Search API - 提供高质量的搜索结果和文本摘要
  • 🌐 Streamable HTTP 传输 - 支持 Server-Sent Events 流式传输
  • 🔐 双重认证机制 - MCP token + 博查AI API key 双重安全
  • 📊 丰富搜索功能 - 网页搜索、图片搜索、时间筛选、域名限定
  • 🛡️ 企业级安全 - CORS 支持、请求验证、错误处理
  • 📡 健康检查 - 完整的服务监控和状态检查
  • 📝 详细日志 - 操作审计和故障排查
  • ⚡ 高性能 - 异步处理、连接池、超时控制

🚀 快速开始

安装依赖

# 使用 pip
pip install -r requirements.txt

# 或使用 uv
uv sync

环境配置

  1. 复制环境变量模板：
cp .env.example .env
  1. 编辑 .env 文件，配置必要的 API keys：
# MCP 服务器认证 token (自定义)
MCP_API_TOKEN=your-secret-token-here

# 博查AI API key (必须从 https://open.bochaai.com 获取)
BOCHA_API_KEY=your-bocha-api-key-here

# 服务器配置
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO

启动服务

# 启动 MCP 服务器
python web_search_server.py

# 或使用 uvicorn
uvicorn web_search_server:app --host 0.0.0.0 --port 8000

服务器将在 http://localhost:8000 启动，提供以下端点：

  • /mcp - MCP 协议端点
  • /health - 健康检查端点

🔧 API 使用

可用工具

1. web_search

执行网络搜索的主要工具

参数:

  • query (str, 必需): 搜索查询字符串
  • count (int, 可选): 返回结果数量，默认 10，范围 1-50
  • freshness (str, 可选): 搜索时间范围
    • 可选值: noLimit, oneDay, oneWeek, oneMonth, oneYear, YYYY-MM-DD..YYYY-MM-DD, YYYY-MM-DD
  • summary (bool, 可选): 是否显示文本摘要，默认 False
  • include_domains (str, 可选): 限定搜索的网站范围，多个域名用 | 分隔
  • exclude_domains (str, 可选): 排除搜索的网站范围，多个域名用 | 分隔

示例:

# 基本搜索
result = await session.call_tool("web_search", {
    "query": "Python编程教程",
    "count": 5
})

# 高级搜索
result = await session.call_tool("web_search", {
    "query": "人工智能最新发展",
    "freshness": "oneMonth",
    "include_domains": "zhihu.com|csdn.net",
    "summary": True
})
2. get_search_info

获取 API 信息和配置参数

返回:

  • 搜索提供商信息
  • 参数说明和选项
  • 响应格式说明

认证方式

所有请求都需要在 Header 中包含有效的 Bearer token：

Authorization: Bearer your-secret-token

🧪 客户端示例

Python 客户端

# 设置环境变量
export MCP_SERVER_URL=http://localhost:8000/mcp
export MCP_API_TOKEN=your-secret-token-here

# 运行示例客户端
python example_client.py

curl 测试

# 健康检查
curl -H "Authorization: Bearer your-token" http://localhost:8000/health

# 测试 MCP 连接
curl -H "Authorization: Bearer your-token" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' \
  http://localhost:8000/mcp

# 执行搜索
curl -H "Authorization: Bearer your-token" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"web_search","arguments":{"query":"人工智能","count":3}}}' \
  http://localhost:8000/mcp

📁 项目结构

bocha-mcp/
├── web_search_server.py      # 主服务器实现
├── example_client.py        # 客户端使用示例
├── requirements.txt         # Python 依赖列表
├── pyproject.toml           # 项目配置文件
├── .env.example            # 环境变量模板
├── README.md               # 项目文档
└── .gitignore              # Git 忽略文件

🔧 开发指南

开发环境设置

# 安装开发依赖
pip install -e ".[dev]"

# 代码格式化
black .
isort .

# 类型检查 (如果使用 mypy)
mypy .

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_server.py

日志配置

服务器支持详细的日志记录：

# 设置日志级别
LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR

# 日志包含
- 请求认证状态
- API 调用详情
- 搜索结果统计
- 错误和异常信息

🚀 部署选项

Docker 部署

# 构建镜像
docker build -t web-search-mcp-server .

# 运行容器
docker run -p 8000:8000 \
  -e MCP_API_TOKEN=your-secret-token \
  -e BOCHA_API_KEY=your-bocha-api-key \
  web-search-mcp-server

生产环境部署

# 使用 gunicorn + uvicorn
pip install gunicorn
gunicorn web_search_server:app -w 4 -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --log-level info

# 或使用 systemd (Linux)
sudo systemctl enable web-search-mcp
sudo systemctl start web-search-mcp

反向代理配置

Nginx 配置示例:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

🔍 故障排除

常见问题

  1. 连接失败

    检查: 服务器状态、URL 配置、网络连接
解决: 确认服务正在运行，检查防火墙设置

  2. 认证失败 (401)

    检查: MCP_API_TOKEN、Authorization header 格式
解决: 确保使用正确的 Bearer token 格式

  3. 搜索 API 失败

    检查: BOCHA_API_KEY、API 余额、网络连接
解决: 验证 API key 有效性，检查博查AI服务状态

  4. 参数验证错误

    检查: count 范围 (1-50)、域名格式
解决: 确保参数符合 API 要求

性能优化

  • 连接池: 使用 HTTPX 连接池提高并发性能
  • 缓存: 考虑对常见查询添加缓存层
  • 限流: 实现请求速率限制防止 API 滥用
  • 监控: 添加 Prometheus 指标监控

📚 API 文档

博查AI Web Search API

MCP 协议

🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

  1. Fork 本项目
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建 Pull Request

开发规范

  • 遵循 PEP 8 代码风格
  • 添加适当的类型注解
  • 编写测试用例
  • 更新相关文档

📄 许可证

本项目采用 MIT 许可证 - 查看 文件了解详情。

🙏 致谢

📞 联系方式

如有问题或建议，请通过以下方式联系：

⭐ 如果这个项目对你有帮助，请考虑给个 Star！