{
  "markdown": "# iflow-search-js\n\nJavaScript / TypeScript integrations for **iFlow Search (心流搜索)** — a search API that provides web search, image search, and web page fetching with AI-friendly structured output.\n\n- **Product:** <https://platform.iflow.cn/>\n- **API docs:** <https://platform.iflow.cn/docs/>\n- **Operator:** 杭州星辰千寻科技有限公司\n\nThis monorepo contains:\n\n- A framework-agnostic core SDK\n- A LangChain JS tool adapter (also usable from LangGraph)\n- A LangGraph agent example\n- An MCP stdio server for Hermes / Claude Code / Claude Desktop / other MCP clients\n\n## Package / usage matrix\n\n| Path | Package | Status | Publish target | Depends on | When to use |\n|---|---|---|---|---|---|\n| `packages/search-core` | `@iflow-ai/search-core` | implemented | npm | — (zero runtime deps) | You are building a framework adapter, calling iFlow directly from a backend, or you don't use LangChain. |\n| `packages/search-langchain` | `@iflow-ai/search-langchain` | implemented | npm | `@iflow-ai/search-core`, `@langchain/core`, `zod` | You are building a LangChain JS agent **or** a LangGraph agent — both reuse the same tool factories. |\n| `examples/langgraph-agent` | `@iflow-examples/langgraph-agent` | implemented | **not published** (workspace example) | `@iflow-ai/search-langchain`, `@langchain/langgraph` | Reference for wiring `createReactAgent` with iFlow Search tools. Copy the pattern, don't depend on it. |\n| `packages/search-mcp` | `@iflow-ai/search-mcp` | implemented | npm | `@iflow-ai/search-core`, MCP SDK | You want to expose iFlow Search to MCP clients (Hermes Agent, Claude Code, Claude Desktop, etc.). Stdio transport. |\n| `plugins/iflow-search` | (Claude Code Plugin manifest) | implemented | Anthropic Plugin Directory (pending) | `@iflow-ai/search-mcp` (npm) | You are a Claude Code user and want one-click `/plugin install` of iFlow Search. Metadata-only; reuses the npm package. |\n\n### Why there is no `@iflow-ai/search-langgraph`\n\nLangGraph consumes LangChain tools directly. A separate `search-langgraph` package would be a thin re-export with no added value — use `@iflow-ai/search-langchain` for both. See `examples/langgraph-agent` for a working `createReactAgent` wiring.\n\n## Current status\n\n- ✅ `@iflow-ai/search-core` — implemented, framework-agnostic client\n- ✅ `@iflow-ai/search-langchain` — implemented, three tools (`iflow_web_search`, `iflow_image_search`, `iflow_web_fetch`)\n- ✅ `examples/langgraph-agent` — implemented, ReAct agent end-to-end smoke validated against real iFlow API\n- ❌ no separate `@iflow-ai/search-langgraph` package (intentional — see above)\n- ✅ `@iflow-ai/search-mcp` — implemented, stdio MCP server with three tools mirroring the LangChain adapter; optional MCP-host attribution via `IFLOW_MCP_CLIENT` / `IFLOW_MCP_CLIENT_VERSION`\n- ✅ `plugins/iflow-search` — Claude Code Plugin manifest (metadata-only, runs `npx -y @iflow-ai/search-mcp`); awaiting submission to the Anthropic Plugin Directory. See [`plugins/iflow-search/README.md`](plugins/iflow-search/README.md).\n\n## Workspace development\n\n```bash\npnpm install\npnpm -r run typecheck\npnpm -r run build\npnpm -r run test\n```\n\nThe workspace pins `@langchain/core` to `^1.1.44` via `pnpm-workspace.yaml` `overrides:` to keep LangGraph's runtime and LangChain's tool types on a single major. Removing this override re-introduces `ToolMessage` cross-version serialization bugs in LangGraph agent loops; rerun the LangGraph agent tests before you touch it.\n\n## Basic usage — core SDK\n\n```ts\nimport { createIFlowSearchClient } from \"@iflow-ai/search-core\";\n\nconst client = createIFlowSearchClient({\n  apiKey: process.env.IFLOW_API_KEY!,\n  source: \"core\",\n  integrationName: \"my-app\",\n  integrationVersion: \"1.0.0\",\n});\n\nconst result = await client.webSearch({ query: \"flash attention\", count: 5 });\nif (!result.ok) {\n  console.error(result.error.code, result.error.message);\n} else {\n  for (const r of result.data.results) console.log(r.title, r.url);\n}\n```\n\nSee `packages/search-core/README.md` for the full API surface.\n\n## Basic usage — LangChain\n\n```ts\nimport { createIFlowSearchTools } from \"@iflow-ai/search-langchain\";\n\nconst tools = createIFlowSearchTools({\n  apiKey: process.env.IFLOW_API_KEY!,\n});\n\n// Hand `tools` to any LangChain JS agent that supports `bindTools`.\n```\n\nSee `packages/search-langchain/README.md` for tool-by-tool docs.\n\n## Basic usage — LangGraph\n\nLangGraph does **not** need a separate iFlow package. Pass the same `@iflow-ai/search-langchain` tools into `createReactAgent`:\n\n```ts\nimport { createReactAgent, ToolNode } from \"@langchain/langgraph/prebuilt\";\nimport { createIFlowSearchTools } from \"@iflow-ai/search-langchain\";\n\nconst tools = createIFlowSearchTools({ apiKey: process.env.IFLOW_API_KEY! });\nconst agent = createReactAgent({ llm, tools: new ToolNode(tools) });\n```\n\nThe working end-to-end example lives at `examples/langgraph-agent` — bring your own tool-calling LLM (DeepSeek, OpenAI, Anthropic, …).\n\n## Attribution headers\n\nEvery request to iFlow goes through `@iflow-ai/search-core` and carries:\n\n```\nIFlow-Source:              <runtime>\nIFlow-Integration:         <package-name>\nIFlow-Integration-Version: <package-version>\nUser-Agent:                <package-name>/<package-version>\n```\n\nCurrently emitted values:\n\n| Integration | `IFlow-Source` | `IFlow-Integration` |\n|---|---|---|\n| `@iflow-ai/search-langchain` (also from LangGraph) | `langchain` | `@iflow-ai/search-langchain` |\n| `@iflow-ai/search-mcp` | `mcp` | `@iflow-ai/search-mcp` |\n\n`@iflow-ai/search-mcp` additionally emits `IFlow-MCP-Client` and `IFlow-MCP-Client-Version` when the MCP host declares itself via `IFLOW_MCP_CLIENT` / `IFLOW_MCP_CLIENT_VERSION` environment variables (e.g. `hermes`, `claude-code`, `claude-desktop`). Absence of these headers is meaningful — there is no `unknown` placeholder, so hosts that opt out remain indistinguishable from hosts that have not adopted the convention.\n\nLangGraph traffic shows up as `IFlow-Source: langchain` because it consumes the same LangChain adapter — there is no separate `langgraph` source ID for this reason.\n\n## Security / key handling\n\n- Never commit real API keys. Use environment variables (`IFLOW_API_KEY`, plus your LLM provider key for agent examples).\n- Don't write keys into `.env` files that get committed, into `package.json`, or into test fixtures.\n- The unit tests in this repo use fake keys and a mocked `fetch` — they never touch the real iFlow API.\n- Real-API smoke tests are opt-in. The committed smoke scripts (e.g. `packages/search-langchain/scripts/smoke-direct.mjs`) read `IFLOW_API_KEY` from the environment at runtime and never persist it.\n\n## Roadmap\n\n- **P0** ✅ `@iflow-ai/search-core` — framework-agnostic SDK\n- **P1** ✅ `@iflow-ai/search-langchain` — LangChain JS tool adapter\n- **P2** ✅ `examples/langgraph-agent` — LangGraph ReAct agent example\n- **P3** ✅ `@iflow-ai/search-mcp` — MCP server for Hermes / Claude Desktop / other MCP clients\n- **P4** 🟡 docs and examples polish — broader recipes, additional LLM providers\n- **P5** optional — refactor the OpenClaw community iFlow plugin to reuse `@iflow-ai/search-core`\n\n## Maintenance and roadmap\n\nLong-form docs for maintainers and contributors live under [`docs/`](./docs):\n\n- [`docs/package-strategy.md`](./docs/package-strategy.md) — which npm packages we publish, which we explicitly will not, and the decision rubric for new ones.\n- [`docs/integration-roadmap.md`](./docs/integration-roadmap.md) — how each framework (LangChain, LangGraph, OpenClaw, Hermes, Claude Code, iFlow CLI, Open WebUI, Coze, CrewAI) reaches iFlow Search, with phased execution order.\n- [`docs/release-policy.md`](./docs/release-policy.md) — versioning, `next` vs `latest`, the per-release checklist, and the manual publish commands.\n- [`docs/mcp-design.md`](./docs/mcp-design.md) — design for the planned `@iflow-ai/search-mcp` server (P3): package decision, transport scope, tool schema, attribution headers, MCP client config example, and test strategy.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 8022,
  "sha": "b90e7db5d5e8eef7c3ddc3a612c4ed183b9ba9efe86ed1220c4f481b288a41cd",
  "repo_slug": "zhengyanglsun/iflow-search-js",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_zhengyanglsun_iflow_search_b94dfaca/readme"
}