searchAPI Console

搜索控制台

调用同源 POST /search

live request

输入关键词后发起搜索。
结果会显示标题、摘要、URL、provider 和 attempts。

请求日志

读取 GET /logs/recent，显示搜索内容和返回结果

暂无请求日志。
发起一次搜索后这里会显示记录。

配置中心

保存到 config.local.json，立即生效

local only

Provider 优先级

Tavily API Keys（每行一个）

Serper API Keys（每行一个）

请求超时（秒）

Key cooldown（秒）

Fallback

provider 失败后尝试下一个渠道

本页面会完整显示 key；仅建议在本机使用，不要把服务暴露到公网。

正在读取当前配置。

也可以用环境变量

如果没有 config.local.json，服务会读取环境变量；网页保存后优先使用本地配置文件。

TAVILY_API_KEYS=key1,key2,key3
SERPER_API_KEYS=key1,key2

配置优先级与降级

默认先用 Tavily，再 fallback 到 Serper；可以按你的成本和效果调整。

SEARCH_PROVIDER_PRIORITY=tavily,serper
SEARCH_FALLBACK_ENABLED=true
SEARCH_TIMEOUT_SECONDS=20
SEARCH_KEY_COOLDOWN_SECONDS=300

启动服务

启动后打开当前页面，也可以直接调用 HTTP API 或 MCP endpoint。

uv run uvicorn searchapi.app:app \
  --host 127.0.0.1 \
  --port 8000

给 AI 配置

HTTP API / HTTP MCP

MCP Endpoint

下面是按当前页面 URL 自动生成的真实配置文件片段；配置文件只负责连接 MCP 服务，工具参数不写在配置文件里。

{
  "mcpServers": {
    "searchapi": {
      "type": "streamable-http",
      "url": "/mcp"
    }
  }
}

不同 AI 客户端字段名可能略有差异；核心就是 HTTP MCP endpoint 指向当前服务的 /mcp。

MCP 是否可用

后端支持 initialize、tools/list、tools/call。客户端连接后会先初始化，再发现 search_web 工具。

请求参数

这些是 AI 调用 search_web 时传入的工具参数，不是 MCP server 配置项：query 必填；limit 默认 5，范围 1-20；provider 可选；search_type 默认 web。

{
  "query": "agent search API",
  "limit": 5,
  "provider": "serper",
  "search_type": "web"
}

返回格式

results 是归一化搜索结果；attempts 会说明调用了哪些 provider、成功还是失败。

{
  "query": "agent search API",
  "provider": "serper",
  "results": [
    {
      "title": "Result title",
      "url": "https://example.com",
      "snippet": "Short summary",
      "provider": "serper",
      "score": null,
      "metadata": {}
    }
  ],
  "attempts": [
    {
      "provider": "serper",
      "status": "success",
      "error": null
    }
  ]
}

手动测试请求

下面这段不是配置文件，只是你想手动验证工具调用时，POST 到 /mcp 的 JSON-RPC 示例。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_web",
    "arguments": {
      "query": "agent search API",
      "limit": 5,
      "provider": "serper"
    }
  }
}

普通 HTTP API

不支持 MCP 的 AI 或脚本可以直接请求 POST /search。

请求参数

query 必填；limit、provider、search_type 可选。返回格式和 MCP 的 structuredContent 一致。

curl -s http://127.0.0.1:8000/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "agent search API",
    "limit": 5
  }'