Content
# SearchAPI MCP Agent with A2A Support
An Agent-to-Agent (A2A) protocol based SearchAPI agent that integrates various search API tools through the Model Context Protocol (MCP) system.
## Overview
SearchAPI-MCP-Agent implements the A2A protocol and Model Context Protocol, encapsulating various search operations as tools and resources. It serves as a bridge between AI assistants and search services, supporting map search, flight queries, hotel bookings, and more.
## Core Features
- **Multiple MCP Configuration** - As an MCP client, can connect to and configure multiple MCP servers simultaneously, expanding the available toolset
- **Dynamic Tool Discovery** - Automatically discovers and loads tool lists provided by MCP servers without manual configuration
- **Intelligent LLM Routing** - Uses Gemini model to automatically route natural language queries to appropriate tools and extract parameters, ensuring successful invocation
- **Real-time Status Feedback** - Provides real-time tool execution status updates and streaming responses to the Host Agent via A2A protocol
- **Error Handling and Recovery** - Automatically handles API call errors, providing friendly error messages and fallback mechanisms
### Google Search
* Web search results
* Knowledge graph integration
* Related questions
* Search suggestions
* Multi-language support
* Region-specific results
* Time range filtering
* Safe search options
### Google Video Search
* Video content search
* Video list retrieval
* Video carousel support
* Short video content
* Duration filtering
* Source filtering
* Upload time sorting
* HD preview support
### Google Maps Search
* Search places and services
* Get place details
* View user reviews
* Get location coordinates
### Google Flights Search
* One-way/round-trip flight search
* Multi-city itinerary planning
* Flight price calendar
* Flight filtering and sorting
* Baggage allowance query
* Airline selection
### Google Hotels Search
* Hotel location search
* Price and availability query
* Facilities and services filtering
* User ratings and reviews
* Special offers query
* Room type selection
## Installation
### Requirements
* Python 3.9 or higher
* pip package manager
* UV package manager (recommended)
### Basic Installation
```bash
# Clone repository
git clone https://github.com/RmMargt/searchapi-mcp-agent.git
cd searchapi-mcp-agent
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or
.\venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
```
### Configure Environment Variables
Create a `.env` file and set the following environment variables:
```
SEARCHAPI_API_KEY=your_searchapi_key_here
GOOGLE_API_KEY=your_google_api_key_here
```
## Usage
### Start the Host Agent and SearchAPI Agent for Google A2A Project
Follow these steps to start a complete A2A environment, including the Host Agent and SearchAPI Agent:
#### 1. Start SearchAPI Agent
```bash
# In the searchapi-mcp-agent directory
python -m searchapi-mcp-agent --host localhost --port 10001
```
#### 2. Start Host Agent (based on Google A2A project)
```bash
# Switch to Google A2A sample directory
cd path/to/A2A/samples/python
# Run Host Agent (choose one)
uv run hosts/cli # Command line interface
# or
uv run hosts/multiagent # Multi-agent environment
```
#### 3. Access Demo UI in Local Browser
If you are running a multi-agent environment, you can access the following address in your browser:
```
http://localhost:12000
```
In the UI, click the robot icon to add the SearchAPI Agent using the following address:
```
http://localhost:10001/agent-card
```
### Send Requests
You can send requests in the following ways:
1. **Natural Language Query**:
```json
{
"query": "Find flights from New York to Los Angeles"
}
```
The agent will use LLM to automatically route the query to the appropriate tool.
2. **Direct Tool Specification**:
```json
{
"tool_name": "search_google_flights",
"parameters": {
"departure_id": "NYC",
"arrival_id": "LAX",
"outbound_date": "2024-12-01"
}
}
```
## A2A Integration
This project fully implements the A2A protocol and can serve as a service endpoint for AI assistants. The API complies with the A2A specification, supporting task creation, status queries, and streaming responses.
### A2A Protocol Implementation
- **Dynamic Tool Routing** - Automatically identifies user intent through natural language processing and selects the appropriate search tool
- **Streaming Responses** - Supports chunked streaming of large search results, providing real-time feedback
- **Task Status Updates** - Reports progress and status changes of search tasks in real-time
- **Error Handling** - Gracefully handles search API errors, providing useful error messages
## MCP Configuration
### Claude for Desktop Configuration Example
Add the following to your Claude for Desktop configuration file:
```json
{
"mcpServers": {
"searchapi": {
"command": "uv",
"args": [
"run",
"--with",
"mcp[cli]",
"/path/to/searchapi-mcp-agent/mcp_server.py"
],
"env": {
"SEARCHAPI_API_KEY": "your_api_key_here",
"GOOGLE_API_KEY": "your_google_api_key_here"
}
}
}
}
```
Configuration file location:
* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
* Model Context Protocol - Protocol specification
* A2A Protocol - Agent-to-Agent protocol specification
* FastMCP - Python MCP implementation
* SearchAPI.io - Search service provider
* Google A2A - A2A protocol reference implementation
---
_Note: This server interacts with external APIs. Always verify that requested operations are appropriate before confirming them in MCP clients._
