Web Cat API

WebCat MCP Server

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 は、AI モデルに以下を提供するMCP（Model Context Protocol）サーバーです。

• 🔍 ウェブ検索 - Serper API（プレミアム）または DuckDuckGo（無料のフォールバック）
• 📄 コンテンツ抽出 - Serper scrape API（プレミアム）または Trafilatura（無料のフォールバック）
• 🌐 最新の HTTP トランスポート - JSON-RPC 2.0 による Streamable HTTP
• 🐳 マルチプラットフォーム Docker - Intel、ARM、Apple Silicon で動作
• 🎯 複合ツール - SERPER_API_KEY 1 つで検索とスクレイピングの両方を利用可能

シームレスな AI 連携を実現するため、FastMCP、Serper.dev、Trafilatura を使用して構築されています。

機能

• ✅ 認証は任意 - 必要に応じて Bearer トークン認証を有効化でき、認証なしでも実行できます（v2.3.1）
• ✅ 複合検索ツール - Serper API キー 1 つで検索とスクレイピングの両方を利用可能
• ✅ 自動フォールバック - 検索：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 キー 1 つで検索とコンテンツのスクレイピングの両方を利用できます！

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 - 最新の HTTP トランスポートを備えた MCP プロトコル実装
• 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

プリコミットフック： コード品質を確保するため、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 非対応： JavaScript で動的にレンダリングされたコンテンツはスクレイピングできません（静的 HTML を使用します）
• PDF 対応： 検出のみで、完全な抽出には対応していません
• Python 3.11 が必須： 3.10 および 3.12 には対応していません
• 外部 API の制限： Serper API のレート制限（月間 2,500 件の無料プラン）の対象となります

コントリビューション

コントリビューションを歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 新機能のテストを追加します
4. make ci が成功することを確認します
5. プルリクエストを送信します

開発ガイドラインとアーキテクチャ標準については、CLAUDE.md を参照してください。

ライセンス

MIT ライセンスです。詳細は LICENSE ファイルを参照してください。

リンク

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

---

バージョン 2.3.2 | FastMCP、FastAPI、Readability、html2text を使用