web-search

# Web Search MCP Server This is a web search server implemented based on MCP (Model Context Protocol), providing a tool interface for web search functionality. ## Project Features The project mainly provides a web search tool that implements search functionality by calling the Zhiyuan AI search API. Key features include: - Provides an asynchronous web search interface - Supports error handling and result parsing - Uses environment variables to configure the API key - Supports standard input/output (stdio) as a transport method ## Tech Stack - Python >= 3.10 - Main dependencies: - httpx: for asynchronous HTTP requests - mcp[cli]: MCP server implementation - python-dotenv: for environment variable management ## Project Structure ``` . ├── main.py # Main program file, containing the MCP server implementation ├── pyproject.toml # Project configuration and dependency management ├── .env # Environment variable configuration file └── README.md # Project documentation ``` ## Main Components ### MCP Server (main.py) Implements a FastMCP server named `web-search-server`, providing the following functionalities: - `web_search` tool: - Receives search query strings - Calls the Zhiyuan AI search API - Processes API responses and returns search results - Supports error handling ### Configuration Files - `pyproject.toml`: Defines project metadata and dependencies - `.env`: Stores API key configuration ## Usage 1. Ensure Python 3.10 or higher is installed 2. Configure environment variables: Set `BIGMODEL_API_KEY` in the `.env` file 3. Install dependencies: Use a package manager to install the dependencies listed in `pyproject.toml` 4. Run the server: Execute `uv run main.py` ## Development Guide ### Setting Up the Development Environment 1. Create and activate a Python virtual environment ```bash uv venv && source .venv/bin/activate # Unix/macOS # or .venv\Scripts\activate # Windows ``` 2. Install development dependencies ```bash uv sync # Install the project in editable mode ``` ### Debugging Methods 1. Debug using mcp ```bash mcp dev main.py ``` 2. Debug using inspector ```bash npx -y @modelcontextprotocol/inspector uv run main.py ``` ### Development Workflow 1. Code Modifications - Follow asynchronous programming patterns - Use type annotations to enhance code readability - Maintain the integrity of error handling 2. Testing and Validation - Run tests to validate changes - Check API response handling - Validate error handling mechanisms 3. Best Practices for Error Handling - API call errors: Check the error field in the response - Network errors: Use try-except to catch httpx exceptions - Parameter validation: Ensure the query string is not empty 4. Performance Optimization Suggestions - Use the context manager of httpx.AsyncClient - Handle concurrent requests appropriately - Consider adding a response caching mechanism ### Common Troubleshooting 1. API Key Issues - Check if the .env file exists - Verify that BIGMODEL_API_KEY is set correctly - Confirm that environment variables are loaded correctly 2. Network Request Issues - Check network connectivity - Verify that the API request URL is correct - Review the format of request headers and parameters 3. Result Parsing Issues - Check if the API response format meets expectations - Validate that JSON parsing is correct - Confirm that the result extraction logic is correct