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 と同じ 3 つのツールを、同じ名前、同じ形式で提供するため、LangChain で iFlow-search-tool エージェントを動かすプロンプトは、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 では、現在の isLatest バージョンとして 0.1.0 が公開されています（0.1.0-pre.2 は過去のエントリーとしてのみ表示されます。詳しくは、以下の Official MCP Registry をご覧ください）。レジストリに保存されるのはメタデータのみです。パッケージ自体は npm からインストールされます。

• トランスポート： stdio のみです。このリリースでは SSE、streamable 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 に掲載されています。

• レジストリ名： io.github.zhengyanglsun/iflow-search
• npm パッケージ： dist-tag latest（0.1.0）の @iflow-ai/search-mcp
• レジストリで追跡されているバージョン： 0.1.0（isLatest: true、status: active）。0.1.0-pre.2 は過去のエントリーとしてのみ残っています。
• トランスポート： stdio

レジストリに保存されるのはメタデータのみで、パッケージ自体は引き続き 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 は省略可能です。設定可能な値については、Configuration の表をご覧ください。指定されていない場合、IFlow-MCP-Client ヘッダーは送信されません（リクエストは引き続き IFlow-Source: mcp として記録されます）。

実際のキーをコミットしないでください。 バージョン管理には YOUR_IFLOW_API_KEY を記載し、実際の値は実行時に注入してください（クライアントのシークレットストア、git で無視されるローカルオーバーライドファイル、direnv ブロックなど）。@iflow-ai/search-mcp はディスクから読み取らず、.env を自動的に読み込むこともありません。

検証済みホスト。 Claude Code は、このパッケージの検証済み MCP ホストです。 Claude Code CLI 2.1.148-20260509.2 と @iflow-ai/[email protected] を使用した stdio のエンドツーエンドスモークテストに合格しており、 実際の iFlow Search API に対して 3 つすべてのツールを実行しています。永続的な Claude Code 設定に影響を与えずに単発のスモークテストや評価を実行するには、セッション単位の設定ファイルを使用し、 claude -p --strict-mcp-config --mcp-config <file> --no-session-persistence … を実行してください。IFLOW_API_KEY は Claude Code の親環境変数の引き継ぎを通じて 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 がサーバーを起動し、3 つのツールを一覧表示できることを確認します。

hermes mcp test iflow-search

注意：

• IFLOW_API_KEY は、サーバーの env: ブロック内で必ず設定してください。Hermes は、親シェルの変数のうち少数の許可リスト（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 は、stdio MCP をネイティブにサポートするターミナル向けコーディングエージェントです。設定は opencode.json（プロジェクト単位）または ~/.config/opencode/opencode.json（ユーザー単位）に記述します。

OpenCode の設定方法が、上記の Claude／Hermes の設定と異なる点は 2 つあります。

1. **トップレベルのブロックは mcp であり、mcpServers ではありません。**また、サーバーごとの環境変数ブロックは env ではなく environment です。command と args は 1 つの command: [...] 配列にまとめます。
2. **IFLOW_API_KEY を environment ブロックに設定しないでください。**OpenCode は、親プロセスの環境変数全体を各 stdio MCP 子プロセスに継承します（anomalyco/opencode の packages/opencode/src/mcp/index.ts を参照してください。env: { ...process.env, ...mcp.environment }）。OpenCode を起動するシェルで IFLOW_API_KEY をエクスポートすれば十分です。キーがコミット対象のファイルに記載されることはありません。environment マップでは ${VAR} 形式のシェル構文は展開されません（Effect スキーマは Record<string, string> であり、そのまま使用されます）。そのため、値として "${IFLOW_API_KEY}" と記述すると、文字列がそのまま MCP 子プロセスに渡され、iFlow 認証に失敗します。

シェルでキーを一度エクスポートします。

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
    }
  }
}

既存の packages/search-mcp/src/config.ts にある [a-z0-9._-]{1,64} の検証で IFLOW_MCP_CLIENT: opencode は許可されます。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 ツール名にサーバー名のプレフィックスを付けます。**LLM には 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／ストリーム可能な HTTP の利用は推奨されません。

CrewAI

CrewAI は Python のマルチエージェントフレームワークです。 crewai-tools[mcp] に含まれる MCPServerAdapter クラスを通じて MCP サーバーを利用します。このクラスは stdio の子プロセスを起動し、各 MCP ツールをエージェントが呼び出せる CrewAIMCPTool として公開します。

この方法では、公開済みの既存の @iflow-ai/search-mcp stdio MCP サーバーを使用します。

• 新しい npm パッケージは不要です。
• CrewAI ネイティブの Python パッケージは不要です。crewai-tools[mcp] は、このサーバーを含むあらゆる MCP stdio サーバーとのブリッジとしてすでに機能します。
• IFLOW_API_KEY は Python ソースにハードコードせず、親シェルの環境変数に設定してください。StdioServerParameters.env は MCP の子プロセスに process.env として渡される辞書を受け取ります。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 が一覧表示する 3 つの名前は、このパッケージが出力する MCP の生の名前である iflow_web_search、iflow_image_search、iflow_web_fetch です。モデル駆動型の Crew からも、同じ名前で表示されます。

IFLOW_MCP_CLIENT="crewai" は、packages/search-mcp/src/config.ts にある既存の [a-z0-9._-]{1,64} 検証で許可されるため、CrewAI をホストスラッグとして追加するためのコード変更は不要です。

テスト済みの範囲。 記録された CrewAI のスモークテストでは、MCPServerAdapter によるツール検出（tools/list が想定どおり 3 つすべてのツールを返すこと）と、実際の iFlow API に対する CrewAIMCPTool.run(**kwargs) の直接呼び出しを確認しました。CrewAI の Agent／Task／Crew による、LLM 駆動型のツール選択ループはテストしていません。このテストには認証済みの LLM プロバイダーが必要ですが、これはこのパッケージの通信経路の範囲外です。スモークテストの詳細については、docs/platform-smokes-mcp.md を参照してください。

Cline（VS Code 拡張機能）

Cline は、stdio MCP を標準でサポートする VS Code のコーディングエージェントです。MCP サーバーの定義は ~/.cline/mcp.json（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 設定を再読み込みすると、3 つのツール（iflow_web_search、iflow_image_search、iflow_web_fetch）がエージェントのツール一覧に表示されます。同じサーバーは公式 MCP レジストリで io.github.zhengyanglsun/iflow-search として検出できます。Cline では引き続き npm からパッケージを直接インストールします。

IFLOW_MCP_CLIENT: cline は、packages/search-mcp/src/config.ts にある既存の [a-z0-9._-]{1,64} 検証で許可されるため、Cline をホストスラッグとして追加するためのコード変更は不要です。

~/.cline/mcp.json をコミットしたり共有したりしないでください。 Cline が親シェルやローカルのシークレットマネージャーから IFLOW_API_KEY を設定できる場合は、設定ファイルに値を直接ハードコードするよりも、そちらを優先してください。mcp.json の共有コピーは、含まれるキーがすでに漏えいしたものとして扱ってください。@iflow-ai/search-mcp はディスクから読み込まず、残っている .env も使用しません。そのため、キーを設定する必要があるのは、Cline が子プロセスに渡す env ブロックだけです。

autoApprove: []（上記のデフォルト設定）では、すべてのツール呼び出しに Cline の承認 UI が必要になります。安全性が確認されたクエリを使って接続を最初から最後まで検証するまでは、この設定のままにしてください。

クライアントを再起動すると、次の 3 つのツールが自動的に表示されます。

ツール	機能
iflow_web_search	iFlow でウェブを検索します。タイトル、URL、スニペットを返します。
iflow_image_search	画像を検索します。画像 URL、タイトル、ソースページを返します。
iflow_web_fetch	単一 URL の読み取り可能な内容を取得します。

設定

すべての設定は process.env から読み込まれます。上記の MCP クライアント設定の env ブロック内で設定してください。

変数	必須	デフォルト	用途
IFLOW_API_KEY	はい	—	iFlow に Authorization: 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 に診断メッセージを1行出力し（JSON-RPC ストリームが破損しないよう stdout には出力しません）、終了コード 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 キーのプロキシ、呼び出しごとのキー上書きには対応しません。
• プロンプトやリソースは同梱していません。検索ツール3つのみです。

クレジット表記

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 を参照してください。