iFlow Search

@iflow-ai/search-mcp

适用于 iFlow Search 的 MCP（Model Context Protocol）服务，可向任何 MCP 客户端（Claude Code、Claude Desktop 及其他兼容宿主）提供网页搜索、图片搜索和网页抓取功能。

基于 @iflow-ai/search-core 构建。与 @iflow-ai/search-langchain 使用相同的三个工具，名称和 结构也相同——因此，在 LangChain 中驱动 iFlow 搜索工具 Agent 的提示词， 无需修改即可在 MCP 中继续使用。

状态 — MVP 稳定版（0.1.0）

@iflow-ai/[email protected] 已发布到 dist-tag latest。直接执行 npm install @iflow-ai/search-mcp 会安装稳定版。@next 仍是预发布渠道，目前指向 0.1.0-pre.2；仅当你需要跟进即将发布的预发布版本时才使用它。 运行 npm view @iflow-ai/search-mcp dist-tags --json 可查看实时状态。

Official MCP Registry 条目 io.github.zhengyanglsun/iflow-search 将 0.1.0 列为当前 isLatest 版本（0.1.0-pre.2 仍仅作为历史条目显示——详见下文的 Official MCP Registry）。Registry 仅存储元数据；软件包本身仍从 npm 安装。

• 传输方式： 仅支持 stdio。本次发布不支持 SSE、可流式传输的 HTTP 或 WebSocket。
• 工具： iflow_web_search、iflow_image_search、iflow_web_fetch。
• 配置： 仅使用环境变量，通过 MCP 客户端的 env 块提供（绝不通过 CLI 标志、点文件、钥匙串或文件发现机制提供）。

安装

pnpm add @iflow-ai/search-mcp
# or
npm install @iflow-ai/search-mcp

Node ≥ 18。

Official MCP Registry

此服务已列入 Official MCP Registry：

• Registry 名称： io.github.zhengyanglsun/iflow-search
• npm 软件包： dist-tag latest 上的 @iflow-ai/search-mcp（0.1.0）
• Registry 跟踪的版本： 0.1.0（isLatest: true，status: active）。0.1.0-pre.2 仅作为历史条目保留。
• 传输方式： stdio

Registry 仅存储元数据——软件包本身仍从 npm 安装。MCP 客户端通过 npx -y @iflow-ai/search-mcp 启动服务，此命令会安装当前稳定版（0.1.0）；也可以锁定具体版本（例如 @iflow-ai/[email protected]）以确保可复现。@next 仍可用于预发布版本测试。

在 MCP 客户端中使用

Claude Code / Claude Desktop / 通用 mcpServers JSON

在客户端的 mcpServers 配置中添加一个条目：

{
  "mcpServers": {
    "iflow-search": {
      "command": "npx",
      "args": ["-y", "@iflow-ai/search-mcp"],
      "env": {
        "IFLOW_API_KEY": "YOUR_IFLOW_API_KEY",
        "IFLOW_MCP_CLIENT": "claude-code"
      }
    }
  }
}

对于 Claude Desktop，配置方式相同，但请将 IFLOW_MCP_CLIENT 设为 claude-desktop，以便后端分析区分这两个客户端：

"env": {
  "IFLOW_API_KEY": "YOUR_IFLOW_API_KEY",
  "IFLOW_MCP_CLIENT": "claude-desktop"
}

IFLOW_MCP_CLIENT 为可选项——允许的取值请参阅配置 表。如果未设置，则不会发送 IFlow-MCP-Client 标头（请求仍会归因于 IFlow-Source: mcp）。

请勿提交真实密钥。 将 YOUR_IFLOW_API_KEY 放入版本控制， 并在运行时注入真实值（使用客户端的密钥存储、本地且被 git 忽略的覆盖文件、 direnv 配置块等）。@iflow-ai/search-mcp 不会读取磁盘文件，也不会自动加载 .env。

已验证的宿主。 Claude Code 是此软件包已验证的 MCP 宿主—— 已在 @iflow-ai/[email protected] 上通过端到端 stdio 冒烟测试， 使用 Claude Code CLI 2.1.148-20260509.2，并通过真实的 iFlow Search API 测试了全部三个工具。若要运行一次性冒烟测试或评估，且不应触及你持久化的 Claude Code 配置，请使用会话级配置文件： claude -p --strict-mcp-config --mcp-config <file> --no-session-persistence … 并通过 Claude Code 的父进程环境变量传递机制，将 IFLOW_API_KEY 传给 MCP 子进程（不要将密钥写入临时的 mcp.json）。复现示例见 docs/platform-smokes-mcp.md。

Hermes Agent

将服务添加到 ~/.hermes/config.yaml：

# ~/.hermes/config.yaml
mcp_servers:
  iflow-search:
    command: npx
    args:
      - -y
      - "@iflow-ai/search-mcp@next"
    env:
      IFLOW_API_KEY: YOUR_IFLOW_API_KEY
      IFLOW_MCP_CLIENT: hermes

验证 Hermes 能否启动服务并列出它的三个工具：

hermes mcp test iflow-search

注意：

• IFLOW_API_KEY 必须在服务的 env: 块中设置。Hermes 只会将父 shell 环境变量中的一个小型允许列表（PATH、HOME、USER 等）传递给 MCP 子进程；其他变量（包括你的 iFlow 密钥）都必须在此处声明。分享任何内容时，请将 YOUR_IFLOW_API_KEY 保留为占位符，切勿提交真实密钥。
• IFLOW_MCP_CLIENT: hermes 会为每个出站请求添加 IFlow-MCP-Client: hermes 标头，以便后端分析区分 Hermes 流量与 Claude Code / Claude Desktop 流量。此字段可选，但建议设置。
• 稳定版 0.1.0 位于 dist-tag latest 上；上面显示的裸名称 @iflow-ai/search-mcp 会解析到该版本。若要确保升级结果可预测，请固定为注册表索引公布的具体版本（例如 @iflow-ai/[email protected]）——运行 npm view @iflow-ai/search-mcp dist-tags --json 查看当前状态。@next（本文撰写时为 0.1.0-pre.2）仍在发布，供预发布测试使用。
• 仅支持 stdio：Hermes 会将二进制文件作为子进程运行，并通过 stdin/stdout 使用 JSON-RPC。无需设置 url / headers 字段。

OpenCode

OpenCode 是一款终端编码 Agent，原生支持 stdio MCP。配置文件位于 opencode.json（项目级）或 ~/.config/opencode/opencode.json（用户级）。

OpenCode 的配置方式与上面的 Claude / Hermes 配置块有两点不同：

1. 顶层配置块是 mcp，而非 mcpServers，且每个服务的环境变量块是 environment，而非 env。command 和 args 会合并到同一个 command: [...] 数组中。
2. 不要将 IFLOW_API_KEY 放入 environment 块。 OpenCode 会将父进程的完整环境变量继承到每个 stdio MCP 子进程中（参见 anomalyco/opencode 中的 packages/opencode/src/mcp/index.ts：env: { ...process.env, ...mcp.environment }）。只需在启动 OpenCode 的 shell 中导出 IFLOW_API_KEY 即可——密钥不会出现在任何已提交的文件中。environment 映射不会展开 ${VAR} shell 语法（Effect schema 为 Record<string, string>，值会原样传递），因此将 "${IFLOW_API_KEY}" 写作值会把字面字符串发送给 MCP 子进程，导致 iFlow 身份验证失败。

在 shell 中导出一次密钥：

export IFLOW_API_KEY="YOUR_IFLOW_API_KEY"

然后在 opencode.json 中仅填写非机密值：

{
  "mcp": {
    "iflow-search": {
      "type": "local",
      "command": ["npx", "-y", "@iflow-ai/search-mcp@next"],
      "environment": {
        "IFLOW_MCP_CLIENT": "opencode"
      },
      "enabled": true
    }
  }
}

IFLOW_MCP_CLIENT: opencode 符合 packages/search-mcp/src/config.ts 中现有的 [a-z0-9._-]{1,64} 校验规则——无需修改代码即可将 OpenCode 添加为宿主标识。

无需启动 TUI，即可验证配置：

opencode mcp list

运行成功时会打印 ✓ iflow-search connected。添加 --print-logs --log-level INFO 可确认工具发现情况——子进程返回 tools/list 后，OpenCode 会记录 service=mcp key=iflow-search toolCount=3 create() successfully created client。

OpenCode 会在其工具注册表中为 MCP 工具添加服务名称前缀。 你的大模型会看到 iflow-search_iflow_web_search、iflow-search_iflow_image_search、iflow-search_iflow_web_fetch。tools/list 返回的原始 MCP 名称仍为 iflow_web_search / iflow_image_search / iflow_web_fetch；iflow-search_ 前缀属于 OpenCode 的命名空间，并非此软件包的一部分。

此处支持的传输方式是 stdio。OpenCode 也支持远程 MCP（type: "remote" 搭配 url），但此软件包仅提供 stdio 二进制文件——不适用 SSE / streamable-HTTP 方案。

CrewAI

CrewAI 是一个 Python 多 Agent 框架。 它通过 crewai-tools[mcp] 中提供的 MCPServerAdapter 类接入 MCP 服务。该类会启动 stdio 子进程，并将每个 MCP 工具作为 CrewAIMCPTool 暴露，供你的 Agent 调用。

此方案使用现有的已发布 @iflow-ai/search-mcp stdio MCP 服务：

• 无需新的 npm 包。
• 无需 CrewAI 原生 Python 包——crewai-tools[mcp] 已可接入任何 MCP stdio 服务，包括此服务。
• 将 IFLOW_API_KEY 保存在父 Shell 环境中，而不要硬编码在 Python 源代码里。StdioServerParameters.env 接受一个字典，并会将其 作为 process.env 传递给 MCP 子进程；将 os.environ 展开到其中 即可转发密钥，无需将其写入任何受版本控制的文件。

安装（crewai-tools 要求 Python 3.10–3.13）：

pip install "crewai-tools[mcp]"

最简用法：

import os
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters

server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@iflow-ai/search-mcp@next"],
    env={**os.environ, "IFLOW_MCP_CLIENT": "crewai"},
)

with MCPServerAdapter(server_params) as tools:
    print([tool.name for tool in tools])
    # → ['iflow_web_search', 'iflow_image_search', 'iflow_web_fetch']
    # tools can be passed to CrewAI Agents (agent=Agent(tools=tools, ...))
    # or invoked directly in smoke tests via tool.run(**kwargs)

CrewAI 不会在 MCP 工具名称前添加服务标识——MCPServerAdapter 列出的三个名称是此包发出的原始 MCP 名称：iflow_web_search、iflow_image_search、 iflow_web_fetch。由模型驱动的 Crew 会以相同名称看到这些工具。

现有的 packages/search-mcp/src/config.ts 中的 [a-z0-9._-]{1,64} 验证 接受 IFLOW_MCP_CLIENT="crewai"——无需更改代码即可将 CrewAI 添加为宿主标识。

已测试范围。 记录的 CrewAI 烟雾测试验证了 MCPServerAdapter 工具发现（tools/list 返回了全部三个预期工具）， 以及针对真实 iFlow API 的直接 CrewAIMCPTool.run(**kwargs) 调用。未测试由 LLM 驱动的完整 CrewAI Agent / Task / Crew 工具选择循环——此流程需要经过身份验证的 LLM 提供商，不属于此 包的通信路径。有关烟雾测试详情，请参阅 docs/platform-smokes-mcp.md。

Cline（VS Code 扩展）

Cline 是一款内置 stdio MCP 支持的 VS Code 编码 Agent。 它从 ~/.cline/mcp.json 读取 MCP 服务定义（macOS/Linux；Windows 上的对应用户路径亦可）。

添加一个指向稳定版包的 iflow-search 条目——npx -y 无需全局安装即可解析当前的 latest 版本：

{
  "mcpServers": {
    "iflow-search": {
      "command": "npx",
      "args": ["-y", "@iflow-ai/search-mcp"],
      "env": {
        "IFLOW_API_KEY": "YOUR_IFLOW_API_KEY",
        "IFLOW_MCP_CLIENT": "cline"
      },
      "autoApprove": []
    }
  }
}

Cline 重新加载 MCP 配置后，三个工具—— iflow_web_search、iflow_image_search、iflow_web_fetch——会显示在 Agent 的工具列表中。也可以在官方 MCP 注册表中找到同一服务，名称为 io.github.zhengyanglsun/iflow-search；Cline 仍会直接从 npm 安装此 包。

packages/search-mcp/src/config.ts 中现有的 [a-z0-9._-]{1,64} 验证接受 IFLOW_MCP_CLIENT: cline——无需更改代码 即可将 Cline 添加为宿主标识。

不要提交或分享 ~/.cline/mcp.json。 如果 Cline 可以从父 Shell 环境或本地密钥管理器注入 IFLOW_API_KEY，请优先使用这种方式，而不要 将实际密钥硬编码到配置文件中。请将任何共享的 mcp.json 副本视为其中的 密钥已经泄露。@iflow-ai/search-mcp 不会读取磁盘内容，也不会读取意外存在的 .env 文件，因此密钥只需保存在 Cline 转发给子进程的 env 块中。

autoApprove: []（上方所示的默认值）会让每次工具调用都必须经过 Cline 的审批界面——在使用已知安全的查询端到端验证配置之前，请保持此设置不变。

客户端重启后，三个工具会自动显示：

工具	功能
iflow_web_search	使用 iFlow 搜索网络。返回标题、URL 和摘要。
iflow_image_search	搜索图片。返回图片 URL、标题和来源页面。
iflow_web_fetch	获取单个 URL 中可阅读的内容。

配置

所有配置均从 process.env 读取。在上方 MCP 客户端配置的 env 代码块中设置这些变量。

变量	必填	默认值	用途
IFLOW_API_KEY	是	—	作为 Authorization: Bearer ... 发送给 iFlow 的 Bearer 令牌。
IFLOW_BASE_URL	否	https://platform.iflow.cn	用于测试／私有部署的覆盖值。
IFLOW_TIMEOUT_MS	否	30000	单次请求的超时时间。设置时必须为正整数。
IFLOW_MCP_CLIENT	否	—	声明的 MCP 主机名称（例如 hermes、claude-code、claude-desktop、opencode、crewai）。设置后，会作为 IFlow-MCP-Client 标头发送，以便后端分析区分不同主机。允许的值：[a-z0-9._-]{1,64}。未设置时不发送标头（我们绝不会发送 unknown 之类的占位符）。
IFLOW_MCP_CLIENT_VERSION	否	—	上述主机的可选版本。两者都设置时，会作为 IFlow-MCP-Client-Version 发送。允许的值：[A-Za-z0-9._+-]{1,64}。仅当设置了 IFLOW_MCP_CLIENT 时才会生效。

配置缺失或无效会导致初始化失败：进程会向 stderr 写入一行诊断信息（绝不写入 stdout，以免破坏 JSON-RPC 流），并以代码 1 退出。

程序化 API

如果你想将此服务嵌入自己的主机（自定义传输、测试等）， 此软件包还导出了以下构建模块：

import { createIFlowSearchClient } from "@iflow-ai/search-core";
import { buildServer } from "@iflow-ai/search-mcp";

const client = createIFlowSearchClient({
  apiKey: process.env.IFLOW_API_KEY!,
  source: "mcp",
  integrationName: "@iflow-ai/search-mcp",
  integrationVersion: "0.1.0",
});

const server = buildServer({ client, integrationVersion: "0.1.0" });
// connect `server` to any Transport from @modelcontextprotocol/sdk

此软件包不做的事

MVP 刻意保持精简。以下事项明确不属于本次发布的目标：

• 不支持 HTTP／SSE／WebSocket 传输 — 仅支持 stdio。
• 不支持基于文件的配置、自动发现 .env 或密钥链集成。
• 不支持多租户托管、API 密钥代理或按调用覆盖密钥。
• 不捆绑提示词或资源 — 仅提供三个搜索工具。

署名信息

每个发往 iFlow 的出站请求都会携带：

IFlow-Source: mcp
IFlow-Integration: @iflow-ai/search-mcp
IFlow-Integration-Version: <pkg version>
User-Agent: @iflow-ai/search-mcp/<pkg version>

当 MCP 客户端配置设置了 IFLOW_MCP_CLIENT（以及可选的 IFLOW_MCP_CLIENT_VERSION）时，还会额外发送以下内容：

IFlow-MCP-Client: hermes | claude-code | claude-desktop | ...
IFlow-MCP-Client-Version: <only if IFLOW_MCP_CLIENT_VERSION is set>

这样，iFlow 就能将通过 MCP 服务生成的流量与直接流量、LangChain 或其他适配器生成的流量分别统计，并区分每个请求由哪个 MCP 主机（Hermes／Claude Code／Claude Desktop／自定义主机）生成。IFlow-MCP-Client 的值由操作方声明 — 它不会从 MCP 的 clientInfo 握手中自动检测，因此后端仪表板看到的是稳定的、采用允许列表风格的主机标识符集合，而不是自由格式、由客户端自行报告的字符串。

许可证

MIT。请参阅 LICENSE。