agy-search

把本机 agy（antigravity-cli，后端 Gemini，能真实联网搜索）包装成一个 stdio MCP server，向 Claude Code 暴露 web_search 工具。

为什么需要这个

Claude Code 接本地模型时，内置的 WebSearch 是 Anthropic 服务端工具，搜索由官方 API 后端执行——本地模型/代理不实现该工具，所以 WebSearch 会返回空结果（Did 0 searches），联网搜索能力缺失。

本项目通过 MCP 工具补齐这个缺口：Claude Code 调用 mcp__agy__web_search → server 内部 spawn agy 子进程 → agy 经 Gemini/Google 联网搜索 → 返回结果。

Claude Code ──(stdio JSON-RPC)──► MCP server（长驻）──(tools/call)──► spawn: agy --prompt ... --output-format json ──► Gemini/Google 搜索 ──► 解析 response 回传

前置要求

• agy（antigravity-cli） 已安装并在 PATH 中，版本 ≥ 1.1.8

• uv（Python 包管理器）

• Python 3.14+

安装

git clone <repo-url> && cd agy-search
uv sync          # 安装依赖（fastmcp）

注册到 Claude Code

推荐全局注册（任意目录都可用），用项目 venv 的绝对路径：

claude mcp add agy -s user -- /<绝对路径>/agy-search/.venv/bin/agy-search

验证：

claude mcp list                 # 应列出 agy 且 ✔ Connected
claude mcp get agy              # Scope 应为 User config

注册后，Claude Code 内会出现工具 mcp__agy__web_search。

使用

在 Claude Code 里直接问需要联网的问题即可，模型会自动调用 mcp__agy__web_search：

今天有什么科技新闻？

工具签名：

web_search(query: str) -> str

• query：搜索查询词（自然语言即可，agy 会自行联网检索）

• 返回：agy 的答案文本（通常含来源）

可选：禁用不可用的内置 WebSearch

接本地模型时，内置 WebSearch 不可用却仍会被调用（白白浪费调用次数）。可在 ~/.claude/settings.json 加 permissions.deny 堵掉它，让搜索统一走 agy：

{
  "permissions": {
    "deny": ["WebSearch"]
  }
}

（WebFetch 仍可用，用于抓取已知 URL，不必禁用。）

本地开发

# 跑 server（fastmcp CLI，file:object 格式导入 server 对象，默认 stdio）
uv run fastmcp run src/agy_search/__init__.py:mcp

# 或经 entry point
uv run agy-search

# 单独验证 agy 契约（不经 MCP）
agy --prompt "测试查询" --output-format json --print-timeout 90s

agy 调用契约（关键，有坑）

命令：agy --prompt "<查询>" --output-format json --print-timeout 90s

• 一律用 --prompt 长选项，不用 -p（实测 -p 会返回 flag 解释而非执行任务）。

• --print-timeout 默认 5m 太长，用 90s。

• 返回 JSON 主用字段：response（答案文本）、status（SUCCESS/ERROR）、error。

• 成败判定不能只看 status：实测 status:"ERROR" 时 response 仍可能含完整正确答案。判定逻辑——response 非空（trim 后）即成功并返回（忽略 status）；response 空且 error 非空才算失败。

• 失败时重试 1 次（应对 Eligibility check failed: EOF、SSE 断连等瞬时错误），仍失败则 raise ToolError（MCP 回 isError=True），server 不崩溃。

项目结构

src/agy_search/__init__.py   # 全部实现：FastMCP server + web_search 工具 + agy 调用 + 重试
pyproject.toml               # 依赖 fastmcp，entry point: agy-search = "agy_search:main"

逻辑内聚在单文件，无额外模块。待加第二个工具时再把 agy 调用逻辑抽成独立模块复用。