Web Cat API

WebCat MCP 服务

通过 Model Context Protocol（MCP）为 AI 模型提供网页搜索和内容提取功能

快速开始

Docker（推荐）

# Run with Docker (no setup required)
docker run -p 8000:8000 tmfrisinger/webcat:latest

# With Serper API key for premium search
docker run -p 8000:8000 -e SERPER_API_KEY=your_key tmfrisinger/webcat:latest

# With authentication enabled
docker run -p 8000:8000 -e WEBCAT_API_KEY=your_token tmfrisinger/webcat:latest

支持： linux/amd64、linux/arm64（Intel/AMD、Apple Silicon、AWS Graviton）

本地开发

cd docker
python -m pip install -e ".[dev]"

# Start MCP server with auto-reload
make dev

# Or run directly
python mcp_server.py

什么是 WebCat？

WebCat 是一个MCP（Model Context Protocol）服务，为 AI 模型提供：

• 🔍 网页搜索 - Serper API（高级版）或 DuckDuckGo（免费备用方案）
• 📄 内容提取 - Serper 抓取 API（高级版）或 Trafilatura（免费备用方案）
• 🌐 现代 HTTP 传输 - 使用 JSON-RPC 2.0 的 Streamable HTTP
• 🐳 多平台 Docker - 支持 Intel、ARM 和 Apple Silicon
• 🎯 组合工具 - 只需一个 SERPER_API_KEY，即可同时使用搜索和抓取功能

基于 FastMCP、Serper.dev 和 Trafilatura 构建，可无缝集成 AI。

功能

• ✅ 可选身份验证 - 按需使用 Bearer 令牌身份验证，也可不启用（v2.3.1）
• ✅ 组合搜索工具 - 只需一个 Serper API 密钥，即可同时使用搜索和抓取功能
• ✅ 自动备用方案 - 搜索：Serper → DuckDuckGo | 抓取：Serper → Trafilatura
• ✅ 高级抓取 - 使用 Serper 优化的基础设施，快速提取整洁的内容
• ✅ 智能内容提取 - 返回保留文档结构的 Markdown
• ✅ 符合 MCP 规范 - 可与 Claude Desktop、LiteLLM 和其他 MCP 客户端配合使用
• ✅ 并行处理 - 快速并发抓取
• ✅ 多平台 Docker - 支持 Linux（amd64/arm64）

安装与使用

Docker 部署

# Quick start - no configuration needed
docker run -p 8000:8000 tmfrisinger/webcat:latest

# With environment variables
docker run -p 8000:8000 \
  -e SERPER_API_KEY=your_key \
  -e WEBCAT_API_KEY=your_token \
  tmfrisinger/webcat:latest

# Using docker-compose
cd docker
docker-compose up

本地开发

cd docker
python -m pip install -e ".[dev]"

# Configure environment (optional)
echo "SERPER_API_KEY=your_key" > .env

# Development mode with auto-reload
make dev        # Start MCP server with auto-reload

# Production mode
make mcp        # Start MCP server

可用端点

端点	描述
http://localhost:8000/health	💗 健康检查
http://localhost:8000/status	📊 服务状态
http://localhost:8000/mcp	🛠️ MCP 协议端点（使用 JSON-RPC 2.0 的 Streamable HTTP）

配置

环境变量

变量	默认值	描述
SERPER_API_KEY	(none)	用于高级搜索的 Serper API 密钥（可选；未设置时将使用 DuckDuckGo 作为备用方案）
PERPLEXITY_API_KEY	(none)	用于深度研究工具的 Perplexity API 密钥（可选，可在 https://www.perplexity.ai/settings/api 获取）
WEBCAT_API_KEY	(none)	用于身份验证的 Bearer 令牌（可选；若已设置，所有请求都必须包含 Authorization: Bearer <token>）
PORT	8000	服务端口
LOG_LEVEL	INFO	日志级别（DEBUG、INFO、WARNING、ERROR）
LOG_DIR	/tmp	日志文件目录
MAX_CONTENT_LENGTH	1000000	每篇抓取文章返回的最大字符数

获取 API 密钥

Serper API（用于网页搜索和抓取）：

1. 访问 serper.dev
2. 注册免费套餐（每月 2,500 次搜索 + 抓取）
3. 复制 API 密钥
4. 添加到 .env 文件：SERPER_API_KEY=your_key
5. 注意： 一个 API 密钥即可同时启用搜索和内容抓取！

Perplexity API（用于深度研究）：

1. 访问 perplexity.ai/settings/api
2. 注册并获取 API 密钥
3. 复制 API 密钥
4. 添加到 .env 文件：PERPLEXITY_API_KEY=your_key

启用身份验证（可选）

若要对所有 MCP 工具调用启用 Bearer 令牌身份验证：

1. 生成安全的随机令牌：openssl rand -hex 32
2. 添加到 .env 文件：WEBCAT_API_KEY=your_token
3. 在所有请求中加入：Authorization: Bearer your_token

注意： 如果未设置 WEBCAT_API_KEY，则无需身份验证。

MCP 工具

WebCat 通过 MCP 提供以下工具：

工具	描述	参数
search	搜索网页并提取内容	query: str、max_results: int
scrape_url	抓取指定 URL	url: str
health_check	检查服务健康状态	（无）
get_server_info	获取服务功能信息	（无）

架构

MCP Client (Claude, LiteLLM)
    ↓
FastMCP Server (Streamable HTTP with JSON-RPC 2.0)
    ↓
Authentication (optional bearer token)
    ↓
Search Decision
    ├─ Serper API (premium) → Serper Scrape API (premium)
    └─ DuckDuckGo (free)    → Trafilatura (free)
                                    ↓
                            Markdown Response

技术栈：

• FastMCP - MCP 协议实现，采用现代 HTTP 传输
• JSON-RPC 2.0 - 客户端与服务端通信的标准协议
• Serper API - Google 驱动的搜索 + 优化的网页抓取
• Trafilatura - 后备内容提取（移除导航内容和广告）
• DuckDuckGo - 免费搜索后备方案

测试

cd docker

# Run all unit tests
make test
# OR
python -m pytest tests/unit -v

# With coverage report
make test-coverage
# OR
python -m pytest tests/unit --cov=. --cov-report=term --cov-report=html

# CI-safe tests (no external dependencies)
python -m pytest -v -m "not integration"

# Run specific test file
python -m pytest tests/unit/services/test_content_scraper.py -v

当前测试覆盖率： 所有模块均达到 70% 以上（由 CI 强制执行）

开发

# First-time setup
make setup-dev   # Install all dependencies + pre-commit hooks

# Development workflow
make dev         # Start server with auto-reload
make format      # Auto-format code (Black + isort)
make lint        # Check code quality (flake8)
make test        # Run unit tests

# Before committing
make ci-fast     # Quick validation (~30 seconds)
# OR
make ci          # Full validation with security checks (~2-3 minutes)

# Code quality tools
make format-check   # Check formatting without changes
make security       # Run bandit security scanner
make audit          # Check dependency vulnerabilities

Pre-commit 钩子： 钩子会在 git commit 时自动运行，以确保代码质量。使用 make setup-dev 安装。

项目结构

docker/
├── mcp_server.py          # Main MCP server (FastMCP)
├── cli.py                 # CLI interface for server modes
├── health.py              # Health check endpoint
├── api_tools.py           # API tooling utilities
├── clients/               # External API clients
│   ├── serper_client.py  # Serper API (search + scrape)
│   └── duckduckgo_client.py  # DuckDuckGo fallback
├── services/              # Core business logic
│   ├── search_service.py # Search orchestration
│   └── content_scraper.py # Serper scrape → Trafilatura fallback
├── tools/                 # MCP tool implementations
│   └── search_tool.py    # Search tool with auth
├── models/                # Pydantic data models
│   ├── domain/           # Domain entities (SearchResult, etc.)
│   └── responses/        # API response models
├── utils/                 # Shared utilities
│   └── auth.py           # Bearer token authentication
├── endpoints/             # FastAPI endpoints
├── tests/                 # Comprehensive test suite
│   ├── unit/             # Unit tests (mocked dependencies)
│   └── integration/      # Integration tests (external deps)
└── pyproject.toml         # Project config + dependencies

搜索质量对比

功能	Serper API	DuckDuckGo
费用	付费（提供免费套餐）	免费
质量	⭐⭐⭐⭐⭐ 优秀	⭐⭐⭐⭐ 良好
覆盖范围	全面（由 Google 驱动）	标准
速度	快	快
速率限制	每月 2,500 次（免费套餐）	无

Docker 多平台支持

WebCat 支持多种架构，以广泛兼容不同部署环境：

# Build locally for multiple platforms
cd docker
./build.sh  # Builds for linux/amd64 and linux/arm64

# Manual multi-platform build and push
docker buildx build --platform linux/amd64,linux/arm64 \
  -t tmfrisinger/webcat:2.3.2 \
  -t tmfrisinger/webcat:latest \
  -f Dockerfile --push .

# Verify multi-platform support
docker buildx imagetools inspect tmfrisinger/webcat:latest

自动化发布： 推送版本标签即可通过 GitHub Actions 触发自动化多平台构建：

git tag v2.3.2
git push origin v2.3.2

限制

• 以文本为主： 针对文章内容优化，不适用于多媒体内容
• 不支持 JavaScript： 无法抓取由动态 JS 渲染的内容（使用静态 HTML）
• PDF 支持： 仅检测，不支持完整提取
• 需要 Python 3.11： 与 3.10 或 3.12 不兼容
• 外部 API 限制： 受 Serper API 速率限制约束（免费套餐每月 2,500 次）

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保 make ci 通过
5. 提交 Pull Request

开发指南和架构规范请参阅 CLAUDE.md。

许可证

MIT License - 详情请参阅 LICENSE 文件。

链接

• GitHub： github.com/Kode-Rex/webcat
• MCP 规范： modelcontextprotocol.io
• Serper API： serper.dev

---

版本 2.3.2 | 使用 FastMCP、FastAPI、Readability 和 html2text 构建