Web Search MCP 服务器

Web Search MCP サーバー

これは MCP（Model Context Protocol）に基づいて実装されたウェブ検索サーバーで、ウェブ検索機能のツールインターフェースを提供します。

プロジェクト機能

プロジェクトは主にウェブ検索ツールを提供し、Zhipu AI の検索 API を呼び出すことで検索機能を実装しています。主な特徴は以下の通りです：

• 非同期ウェブ検索インターフェースの提供
• エラーハンドリングと結果解析のサポート
• 環境変数による API キー設定
• 標準入出力（stdio）をトランスポート方式としてサポート

技術スタック

• Python >= 3.10
• 主な依存関係：
  • httpx: 非同期 HTTP リクエスト用
  • mcp[cli]: MCP サーバー実装
  • python-dotenv: 環境変数管理

プロジェクト構造

.
├── main.py          # 主程序文件，包含 MCP 服务器实现
├── pyproject.toml   # 项目配置和依赖管理
├── .env            # 环境变量配置文件
└── README.md       # 项目文档

主要コンポーネント

MCP サーバー（main.py）

web-search-server という名前の FastMCP サーバーを実装し、以下の機能を提供します：

• web_search ツール：
  • 検索クエリ文字列を受け取る
  • Zhipu AI の検索 API を呼び出す
  • API レスポンスを処理して検索結果を返す
  • エラーハンドリングをサポート

設定ファイル

• pyproject.toml: プロジェクトメタデータと依存関係を定義
• .env: API キー設定を保存

使用方法

1. Python 3.10 以上がインストールされていることを確認してください
2. 環境変数を設定します：.env ファイルに BIGMODEL_API_KEY を設定してください
3. 依存関係をインストールします：パッケージマネージャーを使用して pyproject.toml に記載されている依存関係をインストールしてください
4. サーバーを実行します：uv run main.py を実行してください

開発ガイド

開発環境のセットアップ

1. Python 仮想環境を作成してアクティベートします

uv venv && source .venv/bin/activate  # Unix/macOS
# 或
.venv\Scripts\activate  # Windows

2. 開発用依存関係をインストールします

uv sync  # 以可编辑模式安装项目

デバッグ方法

1. mcp でデバッグします

mcp dev main.py

2. inspector でデバッグします

npx -y @modelcontextprotocol/inspector uv run main.py

開発ワークフロー

1. コード修正

   • 非同期プログラミングパターンに従う
   • 型注釈を使用してコード可読性を向上させる
   • エラーハンドリングの完全性を保つ

2. テスト検証

   • テスト機能を実行して変更を検証する
   • API レスポンス処理を確認する
   • エラーハンドリング機構を検証する

3. エラーハンドリングのベストプラクティス

   • API 呼び出しエラー：レスポンスの error フィールドを確認する
   • ネットワークエラー：try-except で httpx 例外をキャッチする
   • パラメータ検証：クエリ文字列が空でないことを確認する

4. パフォーマンス最適化の提案

   • httpx.AsyncClient のコンテキストマネージャーを使用する
   • 並行リクエストを適切に処理する
   • レスポンスキャッシング機構の追加を検討する

よくあるトラブルシューティング

1. API キーの問題

   • .env ファイルが存在するかを確認する
   • BIGMODEL_API_KEY が正しく設定されているかを確認する
   • 環境変数が正しく読み込まれているかを確認する

2. ネットワークリクエストの問題

   • ネットワーク接続を確認する
   • API リクエスト URL が正しいかを確認する
   • リクエストヘッダーとパラメータ形式を確認する

3. 結果解析の問題

   • API レスポンス形式が期待通りかを確認する
   • JSON 解析が正しいかを確認する
   • 結果抽出ロジックが正しいかを確認する