From 7abd8d688620fbfc45fff199a718812f70351ad1 Mon Sep 17 00:00:00 2001 From: zhengyanglsun Date: Mon, 25 May 2026 16:23:15 +0800 Subject: [PATCH 1/2] docs: add iFlow Search OpenAPI server --- README.md | 1 + servers/iflow-search/README.md | 142 +++++++++++++++++++++++++++++++++ 2 files changed, 143 insertions(+) create mode 100644 servers/iflow-search/README.md diff --git a/README.md b/README.md index e16c212..5d46807 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ Reference implementations provided in this repository demonstrate common use-cas - [**Get User Info Server**](servers/get-user-info) - Access and return enriched user profile information from authentication providers or internal systems. - [**SQL Chat Server**](servers/sql) - Connect to SQL databases and automatically generate, execute, and optimize queries based on your database schema and natural language input. Enables chat-based data exploration, leveraging external Retrieval-Augmented Generation (RAG) for advanced query assistance. - [**External RAG Tool Server**](servers/external-rag) - Connect and execute your own Retrieval-Augmented Generation (RAG) pipelines as callable API tools. Easily integrate custom or third-party RAG flows, providing structured access and modular composition for knowledge-intensive applications. +- [**iFlow Search Server**](servers/iflow-search) - Web search, image search, and URL fetch via the [iFlow Search](https://platform.iflow.cn) API, served as an OpenAPI 3.1 tool server. Node-native — runs via `npx -y @iflow-ai/search-openapi@next`, no local source to clone. (More examples and reference implementations will be actively developed and continually updated.) diff --git a/servers/iflow-search/README.md b/servers/iflow-search/README.md new file mode 100644 index 0000000..09e7f7b --- /dev/null +++ b/servers/iflow-search/README.md @@ -0,0 +1,142 @@ +# 🔎 iFlow Search Tool Server + +A Node-native OpenAPI 3.1 tool server that exposes the [iFlow Search](https://platform.iflow.cn) API — web search, image search, and URL fetch — to any OpenAPI-compatible client (Open WebUI, Coze, custom agents). + +> ⚠️ **Convention note.** Unlike the other servers in this repo (Python / FastAPI / uvicorn), iFlow Search is published on **npm** and runs via **`npx`**. There is no `main.py` or `requirements.txt` here — the server *is* the published [`@iflow-ai/search-openapi`](https://www.npmjs.com/package/@iflow-ai/search-openapi) package. Everything below is invocation, configuration, and registration; no local source needs to be edited. + +📦 Built with: +⚡️ Node.js (≥ 18) • 📦 npm / npx • 📜 OpenAPI 3.1 • 🔍 iFlow Search API + +--- + +## 🚀 Quickstart + +No clone required. The server is a single `npx` invocation: + +```bash +# Required: your iFlow API key, exported in the parent shell +export IFLOW_API_KEY="YOUR_IFLOW_API_KEY" + +# Run the server (binds to 0.0.0.0:8787 by default) +npx -y @iflow-ai/search-openapi@next +``` + +Now visit: + +- 🖥️ Swagger UI / interactive docs: `http://localhost:8787/openapi.json` (raw spec) +- ❤️ Health check: `http://localhost:8787/health` + +> The `@next` dist-tag is recommended during the pre-1.0 cycle. Pin to a specific version (e.g. `@iflow-ai/search-openapi@0.1.0-pre.1`) in production to keep upgrades intentional. + +--- + +## 🔧 Configuration + +All configuration is read from environment variables. The server reads `process.env` only — it does **not** load `.env` files or any on-disk configuration. + +| Variable | Required | Default | Purpose | +|---|---|---|---| +| `IFLOW_API_KEY` | yes | — | Bearer token the server sends to iFlow as `Authorization: Bearer …`. **Never put this in a tracked file.** | +| `PORT` | no | `8787` | Listen port. | +| `IFLOW_OPENAPI_AUTH_TOKEN` | no | — | If set, every route except `GET /health` requires `Authorization: Bearer ` from the **caller**. This is an operator-defined gate token in front of the OpenAPI server — it is **not** an iFlow key. Absent ⇒ open mode (no auth on the server's HTTP surface). | +| `IFLOW_OPENAPI_CORS_ORIGIN` | no | — | When set (e.g. `*` or `https://your-openwebui.example.com`), the server emits the appropriate `Access-Control-Allow-*` headers. Required if a browser-side Open WebUI deployment talks to this server cross-origin. | +| `IFLOW_OPENAPI_CLIENT` | no | — | Declared host slug (e.g. `open-webui`) used in the startup banner and in upstream attribution. Allowed pattern: `[a-z0-9._-]{1,64}`. | + +### Example: open mode behind a local Open WebUI (browser-side) + +```bash +export IFLOW_API_KEY="YOUR_IFLOW_API_KEY" + +IFLOW_OPENAPI_CLIENT=open-webui \ + IFLOW_OPENAPI_CORS_ORIGIN='*' \ + PORT=8787 \ + npx -y @iflow-ai/search-openapi@next +``` + +### Example: gated mode (server requires its own bearer) + +```bash +export IFLOW_API_KEY="YOUR_IFLOW_API_KEY" +export IFLOW_OPENAPI_AUTH_TOKEN="YOUR_OPENAPI_AUTH_TOKEN" + +IFLOW_OPENAPI_CLIENT=open-webui \ + PORT=8787 \ + npx -y @iflow-ai/search-openapi@next +``` + +In gated mode, every Open WebUI request must include +`Authorization: Bearer YOUR_OPENAPI_AUTH_TOKEN`. The token is compared with +`timingSafeEqual` server-side. `GET /health` is always reachable so platform +health probes still work. + +--- + +## 🔌 Register in Open WebUI + +1. In Open WebUI, open **Workspace → Tools → Add Tool Server** (or the equivalent OpenAPI tool registration screen for your release). +2. Fill in: + - **URL**: `http://localhost:8787` + - **OpenAPI spec path**: `/openapi.json` + - **Auth**: *None* if the server is in open mode. If you set `IFLOW_OPENAPI_AUTH_TOKEN`, choose **Bearer** and paste `YOUR_OPENAPI_AUTH_TOKEN`. +3. Save. Open WebUI fetches `/openapi.json` and registers the three tools automatically. + +The three iFlow tools become callable from any model that supports tool use. + +--- + +## 📡 API endpoints + +| Method | Path | Purpose | +|---|---|---| +| `GET` | `/health` | Liveness probe. Never gated by `IFLOW_OPENAPI_AUTH_TOKEN`. | +| `GET` | `/openapi.json` | OpenAPI 3.1 document describing the three tool routes. | +| `POST` | `/tools/iflow_web_search` | Web search. Body: `{ "query": "…", "count": 1-10 }`. Returns titles, URLs, snippets. | +| `POST` | `/tools/iflow_image_search` | Image search. Body: `{ "query": "…", "count": 1-10 }`. Returns image URLs, titles, source pages. | +| `POST` | `/tools/iflow_web_fetch` | Fetch the readable contents of a single URL. Body: `{ "url": "https://…" }`. | + +Each tool route is a thin pass-through to the iFlow Search API; request validation, error mapping, and response normalization happen inside the server before any payload is sent over the network. + +### Example call (open mode) + +```bash +curl -sS -X POST http://localhost:8787/tools/iflow_web_search \ + -H 'Content-Type: application/json' \ + -d '{"query":"iflow search","count":3}' +``` + +### Example call (gated mode) + +```bash +curl -sS -X POST http://localhost:8787/tools/iflow_web_search \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer YOUR_OPENAPI_AUTH_TOKEN' \ + -d '{"query":"iflow search","count":3}' +``` + +--- + +## 🔒 Security boundary + +This is the most important section. Read it once. + +- **`IFLOW_API_KEY` stays inside the local `@iflow-ai/search-openapi` server process.** It is read from `process.env`, attached as `Authorization: Bearer …` on outbound requests to `https://platform.iflow.cn`, and never written to disk, never logged, never echoed. +- **Open WebUI never receives `IFLOW_API_KEY`.** The browser / Open WebUI backend only ever sees (a) the URL of this OpenAPI server and (b), if you set one, the operator-defined `IFLOW_OPENAPI_AUTH_TOKEN` bearer. +- **`IFLOW_OPENAPI_AUTH_TOKEN` is NOT an iFlow key.** It is an operator-defined gate token in front of the local OpenAPI server, used only by callers of *this* server (Open WebUI, curl, your own agent). Choose any opaque value you like; it is unrelated to your iFlow account. +- **Do not commit a real `IFLOW_API_KEY`.** Inject it via `export` in the shell that launches `npx`, via your secret store, or via a `direnv` block — never into a tracked file. +- For deployments where Open WebUI must reach the server over the public Internet, terminate TLS at a reverse proxy and either (a) set `IFLOW_OPENAPI_AUTH_TOKEN` so the server enforces a bearer, or (b) enforce auth at the proxy/tunnel layer (Cloudflare Access policy on a named tunnel, an nginx layer that checks a fixed header, a managed API gateway). Do not expose the open mode to the public Internet. + +--- + +## 🧰 Source, issues, contributions + +- 📦 npm: +- 🛠️ Source repo (monorepo containing the server, the core SDK, and the LangChain / MCP adapters): +- ❓ iFlow platform docs: + +Issues and PRs against the server itself live in the source repo above. This folder is the Open WebUI registration recipe. + +--- + +## 📝 License + +MIT — same as the rest of this repository, and same as the published [`@iflow-ai/search-openapi`](https://www.npmjs.com/package/@iflow-ai/search-openapi) package. From 5b821b50f881542ad141f4efd23dc056e541b898 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=87=BB=E6=89=AC?= Date: Tue, 26 May 2026 21:50:12 +0800 Subject: [PATCH 2/2] docs(iflow-search): refresh for stable 0.1.0 release Drop the @next dist-tag from npx invocations now that @iflow-ai/search-openapi 0.1.0 is published on the npm `latest` channel, and rewrite the prerelease pinning note to reflect the stable-version guidance. --- README.md | 2 +- servers/iflow-search/README.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5d46807..0ae9639 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ Reference implementations provided in this repository demonstrate common use-cas - [**Get User Info Server**](servers/get-user-info) - Access and return enriched user profile information from authentication providers or internal systems. - [**SQL Chat Server**](servers/sql) - Connect to SQL databases and automatically generate, execute, and optimize queries based on your database schema and natural language input. Enables chat-based data exploration, leveraging external Retrieval-Augmented Generation (RAG) for advanced query assistance. - [**External RAG Tool Server**](servers/external-rag) - Connect and execute your own Retrieval-Augmented Generation (RAG) pipelines as callable API tools. Easily integrate custom or third-party RAG flows, providing structured access and modular composition for knowledge-intensive applications. -- [**iFlow Search Server**](servers/iflow-search) - Web search, image search, and URL fetch via the [iFlow Search](https://platform.iflow.cn) API, served as an OpenAPI 3.1 tool server. Node-native — runs via `npx -y @iflow-ai/search-openapi@next`, no local source to clone. +- [**iFlow Search Server**](servers/iflow-search) - Web search, image search, and URL fetch via the [iFlow Search](https://platform.iflow.cn) API, served as an OpenAPI 3.1 tool server. Node-native — runs via `npx -y @iflow-ai/search-openapi`, no local source to clone. (More examples and reference implementations will be actively developed and continually updated.) diff --git a/servers/iflow-search/README.md b/servers/iflow-search/README.md index 09e7f7b..db4382d 100644 --- a/servers/iflow-search/README.md +++ b/servers/iflow-search/README.md @@ -18,7 +18,7 @@ No clone required. The server is a single `npx` invocation: export IFLOW_API_KEY="YOUR_IFLOW_API_KEY" # Run the server (binds to 0.0.0.0:8787 by default) -npx -y @iflow-ai/search-openapi@next +npx -y @iflow-ai/search-openapi ``` Now visit: @@ -26,7 +26,7 @@ Now visit: - 🖥️ Swagger UI / interactive docs: `http://localhost:8787/openapi.json` (raw spec) - ❤️ Health check: `http://localhost:8787/health` -> The `@next` dist-tag is recommended during the pre-1.0 cycle. Pin to a specific version (e.g. `@iflow-ai/search-openapi@0.1.0-pre.1`) in production to keep upgrades intentional. +> The current stable release on npm is `@iflow-ai/search-openapi@0.1.0` (the `latest` dist-tag). For reproducible installs, pin the version explicitly — e.g. `npx -y @iflow-ai/search-openapi@0.1.0`. --- @@ -50,7 +50,7 @@ export IFLOW_API_KEY="YOUR_IFLOW_API_KEY" IFLOW_OPENAPI_CLIENT=open-webui \ IFLOW_OPENAPI_CORS_ORIGIN='*' \ PORT=8787 \ - npx -y @iflow-ai/search-openapi@next + npx -y @iflow-ai/search-openapi ``` ### Example: gated mode (server requires its own bearer) @@ -61,7 +61,7 @@ export IFLOW_OPENAPI_AUTH_TOKEN="YOUR_OPENAPI_AUTH_TOKEN" IFLOW_OPENAPI_CLIENT=open-webui \ PORT=8787 \ - npx -y @iflow-ai/search-openapi@next + npx -y @iflow-ai/search-openapi ``` In gated mode, every Open WebUI request must include