SearchAPI MCP Agent 使用说明

本项目是一个功能强大的AI代理，作为人工智能助手与各种搜索服务之间的桥梁。它基于Model Context Protocol (MCP) 和 Agent-to-Agent (A2A) 协议，将多种搜索操作封装为可供AI调用的工具。

项目简介

SearchAPI MCP Agent 允许大型语言模型 (LLM) 或其他AI客户端通过结构化的协议访问外部世界的实时信息。它通过集成 SearchAPI.io 服务，提供了包括网页搜索、地图、航班、酒店、视频等在内的多种搜索功能。本项目同时实现了MCP服务器端，暴露这些搜索能力作为工具供兼容的MCP客户端调用，并集成了A2M（Agent-to-Model）能力，使用LLM进行自然语言查询的工具路由和参数提取。

主要功能点

全面的搜索能力: 支持多种Google搜索服务，包括网页、图片、新闻、视频、地图、航班和酒店等。
AI驱动的工具路由: 利用强大的语言模型（如Gemini）理解用户的自然语言查询，自动识别意图并调用最合适的搜索工具，无需用户知道具体的工具名称或复杂的参数结构。
动态工具发现: MCP客户端可以自动发现此服务器提供的工具列表及其描述，无需手动同步工具信息。
标准化协议: 采用Model Context Protocol (MCP) 和 Agent-to-Agent (A2A) 协议进行通信，确保与兼容客户端的高效和标准交互。
实时状态与流式响应: 通过A2A协议（如果在A2A环境中运行），可以向宿主代理提供任务的实时进度更新和可能的流式结果。

安装步骤

环境准备: 确保您的系统已安装 Python 3.9 或更高版本，以及 pip 包管理器。推荐安装 UV 包管理器以加快依赖安装。

克隆仓库: 使用 Git 克隆本项目的代码到本地。

git clone https://github.com/RmMargt/searchapi-mcp-agent.git
cd searchapi-mcp-agent

创建并激活虚拟环境: 创建一个独立的Python虚拟环境以管理项目依赖。

python -m venv venv
# 在 Linux/macOS 上激活
source venv/bin/activate
# 在 Windows 上激活
.\venv\Scripts\activate

安装依赖: 安装项目所需的所有库。

pip install -r requirements.txt
# 如果使用 UV (推荐)
# uv pip install -r requirements.txt

配置API密钥: 创建一个名为 '.env' 的文件在项目根目录下，并填入您的 SearchAPI.io 和 Google API 密钥。
```
SEARCHAPI_API_KEY=您的SearchAPI_API_密钥
GOOGLE_API_KEY=您的Google_API_密钥
```
- 'SEARCHAPI_API_KEY': 用于访问 SearchAPI.io 服务进行各类搜索。
- 'GOOGLE_API_KEY': 用于项目内部的LLM（Gemini）进行自然语言路由。

服务器配置（供MCP客户端使用）

本项目包含一个MCP服务器实现 ('mcp_server.py')，可以被任何兼容的MCP客户端（如 Claude for Desktop）连接和使用。客户端需要配置服务器的启动方式，通常通过指定 command 和 args 来运行服务器脚本。

例如，在支持MCP服务器配置的MCP客户端中，您可以添加一个服务器配置，指向本项目的 'mcp_server.py' 文件。配置通常是一个 JSON 对象，指定如何启动这个服务器作为客户端的一个子进程。

标准的MCP客户端配置示例结构（请根据您的客户端实际要求进行调整）：

{
  "mcpServers": {
    "searchapi": { // 服务器的唯一名称标识
      "command": "uv", // 或 "python"
      "args": [
        "run",
        "--with",
        "mcp[cli]", // 确保运行mcp_server.py并支持MCP CLI模式
        "/path/to/searchapi-mcp-agent/mcp_server.py" // 替换为mcp_server.py的实际绝对路径
      ],
      "env": { // 可选：将环境变量直接传递给服务器进程，或者依赖系统环境
        "SEARCHAPI_API_KEY": "您的SearchAPI_API_密钥",
        "GOOGLE_API_KEY": "您的Google_API_密钥"
      }
    }
  }
}

'"searchapi"': 这个是您为这个服务器实例指定的名称，客户端会用它来引用。
'"command"': 启动服务器进程的命令，通常是 'python' 或 'uv'。
'"args"': 传递给 'command' 的参数列表，用于指定运行哪个脚本 ('mcp_server.py') 以及如何运行（例如使用 'uv run'）。请务必将 '/path/to/searchapi-mcp-agent/mcp_server.py' 替换为您系统中 'mcp_server.py' 文件的绝对路径。
'"env"': 一个可选的对象，用于设置启动服务器进程时的环境变量，确保API密钥能够被服务器读取。或者您也可以确保在启动MCP客户端的shell环境中已经设置了这些环境变量。

配置完成后，您的MCP客户端应该能够发现并使用由 SearchAPI MCP Agent 提供的搜索工具。

基本使用方法

一旦 SearchAPI MCP Agent 被您的MCP客户端成功配置并连接，您就可以通过客户端的用户界面或API来使用它提供的功能。

通过自然语言查询: 在支持的客户端中，您可以像与AI对话一样输入您的搜索需求。Agent会利用LLM自动理解并调用合适的工具。
- 示例输入: "查找从上海到东京的机票"
- 示例输入: "附近的意大利餐厅在哪里？"
- 示例输入: "给我讲讲人工智能的最新新闻"
- 示例输入: "现在几点了？"
直接指定工具（如果客户端支持）: 如果您知道要使用的具体工具名称，可以直接通过工具调用接口来指定。
- 例如，调用 'search_google_flights' 工具并提供 'departure_id', 'arrival_id', 'outbound_date' 等参数。
- 例如，调用 'search_google_maps' 工具并提供 'query' 参数。

Agent 会执行相应的搜索操作，并将结果通过MCP协议返回给客户端进行展示或进一步处理。

确保您已正确设置 'SEARCHAPI_API_KEY' 和 'GOOGLE_API_KEY' 环境变量或在客户端配置中传递，否则搜索功能将无法正常工作。

关键词