diff --git a/README.md b/README.md
index 53c169a..28f69ed 100644
--- a/README.md
+++ b/README.md
@@ -1,220 +1,268 @@
# Cloudflare Search
-> 基于 Cloudflare Workers 的聚合搜索 API 服务
+English | [中文](./README.zh.md)
-> 支持 **MCP (Model Context Protocol)**，让 AI 助手拥有实时联网搜索能力
+> An aggregated search API service based on Cloudflare Workers
+
+> Supports **MCP (Model Context Protocol)**, giving AI assistants (OpenClaw, Claude Code, Codex, OpenCode) real-time web search capabilities
[](https://sink.proddig.com/cloudflare-search-github)
-## 特性
+## Features
-- 🔍 **多引擎聚合** - 同时使用多个搜索引擎（Google、Brave、DuckDuckGo、Bing）
-- 🤖 **AI 增强 (MCP)** - 原生支持 Model Context Protocol，一键为 Claude Code/Desktop 添加搜索工具
-- ⚡ **并行搜索** - 所有搜索引擎同时请求，快速返回结果
-- 🛡️ **容错机制** - 单个引擎失败不影响其他引擎，自动标记无响应引擎
-- ⏱️ **超时控制** - 可配置请求超时时间，避免长时间等待
-- 🔒 **Token 鉴权** - 支持 Token 认证，保护服务不被滥用
-- 🌍 **CORS 支持** - 完整的跨域资源共享支持
-- 🎨 **Web 界面** - 提供简洁的搜索界面，方便测试
-- ⚡ **零成本运行** - Cloudflare Workers 免费版每天 10 万次请求
+- 🔍 **Multi-engine Aggregation** - Use multiple search engines at the same time (Google, Brave, DuckDuckGo, Bing)
+- 🤖 **AI Enhanced (MCP)** - Native support for Model Context Protocol, one-click search tool integration for **OpenClaw** / **Claude Code** / **Codex**
+- ⚡ **Parallel Search** - All search engines are requested concurrently for faster results
+- 🛡️ **Fault Tolerance** - Failure of a single engine does not affect others; unresponsive engines are automatically marked
+- ⏱️ **Timeout Control** - Configurable request timeout to avoid long waits
+- 🔒 **Token Authentication** - Supports token auth to protect the service from abuse
+- 🌍 **CORS Support** - Full cross-origin resource sharing support
+- 🎨 **Web Interface** - Provides a clean search UI for easy testing
+- ⚡ **Zero-cost Operation** - Cloudflare Workers free tier supports 100,000 requests per day
-## 页面展示
+## Page Preview
-## 安装方式
+## MCP Integration: Use in OpenClaw / Claude Code / AI Agents
-### 方式一：一键部署（推荐）
+With MCP (Model Context Protocol), AI assistants can directly call your search service and get real-time search results.
-点击上方 "Deploy to Cloudflare Workers" 按钮，按照提示完成部署。
+### Installation and Configuration
-### 方式二：使用 Wrangler CLI
+#### 1. Deploy the Service
+
+First, follow the guide to [Deploy Cloudflare Search](#installation-methods)
+
+#### 2. Add MCP Server Configuration
+
+Edit your config file ([configuration guide](https://modelcontextprotocol.io/quickstart/user)):
+
+- **OpenClaw**: `~/.openclaw/openclaw.json`
+- **Claude Code**: `~/.claude/config.json` / `~/.claude.json`
+- **Claude Desktop macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Claude Desktop Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+ "mcpServers": {
+ "cloudflare-search": {
+ "command": "npx",
+ "args": ["-y", "@yrobot/cf-search-mcp"],
+ "env": {
+ "CF_SEARCH_URL": "https://your-worker.workers.dev",
+ "CF_SEARCH_TOKEN": "your-token-here"
+ }
+ }
+ }
+}
+```
+
+**Environment Variables**:
+
+- `CF_SEARCH_URL`: Worker deployment URL (required)
+- `CF_SEARCH_TOKEN`: Auth token (required if your Worker has `TOKEN` configured)
+
+#### 3. Verify Installation
+
+- **OpenClaw**: Run `openclaw gateway restart` + `openclaw mcp list` and check that `cloudflare-search` appears
+- **Claude Code**:
+ - Run `/mcp` in Claude Code, and you should see the `cloudflare-search` tool.
+ - Or run `claude mcp list`; seeing `cloudflare-search: npx -y @yrobot/cf-search-mcp@latest - ✓ Connected` means setup is successful
+
+## Installation Methods
+
+### Method 1: One-click Deployment (Recommended)
+
+Click the "Deploy to Cloudflare Workers" button above and follow the prompts.
+
+### Method 2: Use Wrangler CLI
```bash
-# 1. 安装 Wrangler
+# 1. Install Wrangler
npm install -g wrangler
-# 2. 登录 Cloudflare
+# 2. Login to Cloudflare
wrangler login
-# 3. 克隆仓库
+# 3. Clone the repository
git clone https://github.com/Yrobot/cloudflare-search.git
cd cloudflare-search
-# 4. 部署
+# 4. Deploy
wrangler deploy
```
-### 方式三：使用 Cloudflare Dashboard
+### Method 3: Use Cloudflare Dashboard
-1. 登录 [Cloudflare Dashboard](https://dash.cloudflare.com/)
-2. 进入 **Workers & Pages**
-3. 点击 **Create Application** > **Create Worker**
-4. 点击 **Upload** 上传本地代码文件夹
- - 选择克隆的 `cloudflare-search` 文件夹
- - 或者手动复制 `worker.js`、`envs.js`、`utils/` 等文件
-5. 点击 **Save and Deploy**
+1. Sign in to [Cloudflare Dashboard](https://dash.cloudflare.com/)
+2. Go to **Workers & Pages**
+3. Click **Create Application** > **Create Worker**
+4. Click **Upload** to upload your local code folder
+ - Select the cloned `cloudflare-search` folder
+ - Or manually copy `worker.js`, `envs.js`, `utils/`, and other files
+5. Click **Save and Deploy**
-### 获取访问地址
+### Get Access URL
-部署成功后，你会获得一个 Worker URL：
+After deployment, you will get a Worker URL:
```
https://your-worker-name.your-subdomain.workers.dev
```
-**注意**：这个自带的域名在某些区域可能无法直接访问，建议绑定自己的域名使用。
+**Note**: The default domain may not be directly accessible in some regions. It is recommended to bind your own custom domain.
-## 使用方式
+## Usage
-### 方式 1: Web 界面
+### Method 1: Web Interface
-直接访问你的 Worker URL，在网页界面输入搜索关键词：
+Open your Worker URL directly and enter search keywords in the web UI:
```
https://$YOUR-DOMAIN/
```
-### 方式 2: API 请求（GET）
+### Method 2: API Request (GET)
-使用查询参数进行搜索：
+Search using query parameters:
```bash
-# 基本搜索
+# Basic search
curl "https://$YOUR-DOMAIN/search?q=cloudflare"
-# 指定搜索引擎
+# Specify search engines
curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave"
-# 使用 token 鉴权（如果配置了 TOKEN 环境变量）
+# Use token authentication (if TOKEN env var is configured)
curl "https://$YOUR-DOMAIN/search?q=cloudflare&token=$YOUR-TOKEN"
```
-### 方式 3: API 请求（POST）
+### Method 3: API Request (POST)
-通过 POST 表单提交搜索：
+Submit search by POST form:
```bash
curl -X POST "https://$YOUR-DOMAIN/search" \
- -d "q=cloudflare" \
- -d "engines=google,brave"
- -d "token=$YOUR-TOKEN" # 如果配置了 TOKEN 环境变量
+ -d "q=cloudflare" \
+ -d "engines=google,brave"
+ -d "token=$YOUR-TOKEN" # if TOKEN env var is configured
```
-## API 接口说明
+## API Reference
-### `/search` 接口
+### `/search` Endpoint
-用于执行搜索查询并返回聚合结果。
+Used to execute search queries and return aggregated results.
-#### 请求参数
+#### Request Parameters
-| 参数 | 类型 | 必填 | 说明 | 示例 |
-| ------------- | -------- | ------ | ----------------------------------------- | -------------- |
-| `q` / `query` | `string` | yes | 搜索关键词 | `cloudflare` |
-| `engines` | `string` | no | 指定搜索引擎，多个用逗号分隔 | `google,brave` |
-| `token` | `string` | no/yse | 访问令牌（当配置了 TOKEN 环境变量时必填） | `$YOUR-TOKEN` |
+| Parameter | Type | Required | Description | Example |
+| ------------- | -------- | -------- | ---------------------------------------------------------- | ---------------- |
+| `q` / `query` | `string` | yes | Search keyword | `cloudflare` |
+| `engines` | `string` | no | Specify search engines, separated by commas | `google,brave` |
+| `token` | `string` | no/yes | Access token (required when `TOKEN` env var is configured) | `$YOUR-TOKEN` |
-**支持的搜索引擎**：
+**Supported Search Engines**:
-- `google` - Google 搜索（需要配置 API Key）
-- `brave` - Brave 搜索
-- `duckduckgo` - DuckDuckGo 搜索
-- `bing` - Bing 搜索
+- `google` - Google Search (requires API Key configuration)
+- `brave` - Brave Search
+- `duckduckgo` - DuckDuckGo Search
+- `bing` - Bing Search
-#### 返回值
+#### Response Value
```typescript
{
- query: string; // 搜索关键词
- number_of_results: number; // 结果总数
- enabled_engines: string[]; // 启用的搜索引擎列表
- unresponsive_engines: string[]; // 无响应的搜索引擎列表
- results: Array<{
- title: string; // 结果标题
- description: string; // 结果描述
- url: string; // 结果链接
- engine: string; // 来源引擎
- }>;
+ query: string; // Search keyword
+ number_of_results: number; // Total number of results
+ enabled_engines: string[]; // Enabled search engine list
+ unresponsive_engines: string[]; // Unresponsive search engine list
+ results: Array<{
+ title: string; // Result title
+ description: string; // Result description
+ url: string; // Result link
+ engine: string; // Source engine
+ }>;
}
```
-#### 请求示例
+#### Request Examples
```bash
-# GET 请求
+# GET request
curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave"
-# POST 请求
+# POST request
curl -X POST "https://$YOUR-DOMAIN/search" \
- -H "Content-Type: application/x-www-form-urlencoded" \
- -d "q=cloudflare&engines=google,brave"
+ -H "Content-Type: application/x-www-form-urlencoded" \
+ -d "q=cloudflare&engines=google,brave"
```
-#### 响应示例
+#### Response Example
```json
{
- "query": "cloudflare",
- "number_of_results": 15,
- "enabled_engines": ["google", "brave", "duckduckgo"],
- "unresponsive_engines": [],
- "results": [
- {
- "title": "Cloudflare - The Web Performance & Security Company",
- "description": "Cloudflare is on a mission to help build a better Internet...",
- "url": "https://www.cloudflare.com/",
- "engine": "google"
- },
- {
- "title": "Cloudflare Workers",
- "description": "Deploy serverless code instantly across the globe...",
- "url": "https://workers.cloudflare.com/",
- "engine": "brave"
- }
- ]
+ "query": "cloudflare",
+ "number_of_results": 15,
+ "enabled_engines": ["google", "brave", "duckduckgo"],
+ "unresponsive_engines": [],
+ "results": [
+ {
+ "title": "Cloudflare - The Web Performance & Security Company",
+ "description": "Cloudflare is on a mission to help build a better Internet...",
+ "url": "https://www.cloudflare.com/",
+ "engine": "google"
+ },
+ {
+ "title": "Cloudflare Workers",
+ "description": "Deploy serverless code instantly across the globe...",
+ "url": "https://workers.cloudflare.com/",
+ "engine": "brave"
+ }
+ ]
}
```
-## 搜索引擎说明
+## Search Engine Notes
-### 支持的搜索引擎
+### Supported Search Engines
-| 引擎 | 说明 | 是否需要配置 | 默认启用 |
-| -------------- | ------------------------ | ----------------------------- | --------------- |
-| **Google** | Google Custom Search API | 需要 GOOGLE_API_KEY GOOGLE_CX | yes |
-| **Brave** | Brave Search API | - | yes |
-| **DuckDuckGo** | DuckDuckGo 即时答案 API | - | yes |
-| **Bing** | Bing 搜索 | - | no (结果不稳定) |
+| Engine | Description | Configuration Required | Enabled by Default |
+| -------------- | ---------------------------- | ------------------------------- | ------------------ |
+| **Google** | Google Custom Search API | Requires `GOOGLE_API_KEY` and `GOOGLE_CX` | yes |
+| **Brave** | Brave Search API | - | yes |
+| **DuckDuckGo** | DuckDuckGo Instant Answer API | - | yes |
+| **Bing** | Bing Search | - | no (unstable results) |
-### 基本工作方案
+### Basic Working Approach
-1. **并行请求**：所有启用的搜索引擎同时发起请求，提高响应速度
-2. **超时控制**：单个引擎超时不影响其他引擎，默认 3 秒超时
-3. **结果聚合**：将所有成功返回的结果合并，标记来源引擎
-4. **容错处理**：记录无响应的引擎，返回部分结果而不是完全失败
+1. **Parallel Requests**: All enabled search engines are requested concurrently to improve response speed
+2. **Timeout Control**: Timeout of a single engine does not affect others; default timeout is 3 seconds
+3. **Result Aggregation**: Merge all successfully returned results and mark their source engine
+4. **Fault Tolerance**: Record unresponsive engines and return partial results instead of failing completely
-## 环境变量配置
+## Environment Variable Configuration
-### 环境变量说明
+### Environment Variables
-| 变量名 | 类型 | 默认值 | 说明 |
-| ----------------- | -------- | -------- | ------------------------------------------------- |
-| `DEFAULT_TIMEOUT` | `string` | `"3000"` | 单个搜索引擎的超时时间（毫秒） |
-| `GOOGLE_API_KEY` | `string` | `null` | https://console.cloud.google.com/apis/credentials |
-| `GOOGLE_CX` | `string` | `null` | https://programmablesearchengine.google.com/ |
-| `TOKEN` | `string` | `null` | 访问令牌，配置后启用鉴权，保护服务不被滥用 |
+| Variable Name | Type | Default | Description |
+| ------------------ | -------- | -------- | --------------------------------------------------- |
+| `DEFAULT_TIMEOUT` | `string` | `"3000"` | Timeout per search engine request (milliseconds) |
+| `GOOGLE_API_KEY` | `string` | `null` | https://console.cloud.google.com/apis/credentials |
+| `GOOGLE_CX` | `string` | `null` | https://programmablesearchengine.google.com/ |
+| `TOKEN` | `string` | `null` | Access token. Enables auth when configured to prevent abuse |
-**注意**：
+**Notes**:
-- Google Custom Search API 免费版每天限制 100 次请求
-- `TOKEN` 配置后，所有请求都需要提供有效的 token
+- Google Custom Search API free tier is limited to 100 requests per day
+- After `TOKEN` is configured, all requests must provide a valid token
-### 配置方式
+### Configuration Methods
-#### 方式 1: wrangler.toml 文件
+#### Method 1: `wrangler.toml` File
-编辑 `wrangler.toml` 文件中的 `[vars]` 部分：
+Edit the `[vars]` section in `wrangler.toml`:
```toml
[vars]
@@ -224,218 +272,165 @@ DEFAULT_TIMEOUT = "3000"
TOKEN = "your-secret-token-here"
```
-#### 方式 2: Cloudflare Dashboard
+#### Method 2: Cloudflare Dashboard
-1. 进入 Worker 设置页面
-2. 找到 **Environment Variables** 部分
-3. 添加变量并保存
+1. Go to the Worker settings page
+2. Find the **Environment Variables** section
+3. Add variables and save
-## 使用场景
+## Use Cases
-### 1. 聚合搜索服务
+### 1. Aggregated Search Service
-构建自己的搜索聚合 API，整合多个搜索引擎结果：
+Build your own aggregated search API and combine results from multiple search engines:
```javascript
const response = await fetch(
- "https://$YOUR-DOMAIN/search?q=javascript&engines=google,brave"
+ "https://$YOUR-DOMAIN/search?q=javascript&engines=google,brave",
);
const data = await response.json();
-console.log(`找到 ${data.number_of_results} 个结果`);
+console.log(`Found ${data.number_of_results} results`);
```
-### 2. 前端搜索功能
+### 2. Frontend Search Feature
-为网站或应用添加搜索功能：
+Add search functionality to your website or app:
```javascript
async function search(query) {
- const response = await fetch(
- `https://$YOUR-DOMAIN/search?q=${encodeURIComponent(query)}`
- );
- const data = await response.json();
- return data.results;
+ const response = await fetch(
+ `https://$YOUR-DOMAIN/search?q=${encodeURIComponent(query)}`,
+ );
+ const data = await response.json();
+ return data.results;
}
```
-### 3. 数据采集与分析
+### 3. Data Collection and Analysis
-收集多个搜索引擎的结果进行对比分析：
+Collect results from multiple search engines for comparative analysis:
```javascript
const engines = ["google", "brave", "duckduckgo"];
const results = await fetch(
- `https://$YOUR-DOMAIN/search?q=AI&engines=${engines.join(",")}`
+ `https://$YOUR-DOMAIN/search?q=AI&engines=${engines.join(",")}`,
);
const data = await results.json();
-// 按引擎分组
+// Group by engine
const byEngine = data.results.reduce((acc, result) => {
- acc[result.engine] = acc[result.engine] || [];
- acc[result.engine].push(result);
- return acc;
+ acc[result.engine] = acc[result.engine] || [];
+ acc[result.engine].push(result);
+ return acc;
}, {});
```
-## MCP 集成
+## MCP Integration
-通过 MCP (Model Context Protocol) 让 AI 助手直接调用你的搜索服务，获取实时搜索结果。
+With MCP (Model Context Protocol), AI assistants can directly call your search service and get real-time search results.
-### 安装配置
+## Notes and Reminders
-#### 1. 添加 MCP 服务器配置
+### 🚨 Important Notes
-编辑配置文件（[配置指南](https://modelcontextprotocol.io/quickstart/user)）：
+1. **Use a Custom Domain**
+ - The default Cloudflare `*.workers.dev` domain may be inaccessible in some regions
+ - It is **strongly recommended** to bind your own domain for a better access experience
+ - In Worker settings, click **Triggers** > **Add Custom Domain** to add a custom domain
-- **Claude Code**: `~/.claude/config.json` / `~/.claude.json`
-- **Claude Desktop macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Claude Desktop Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+2. **Search Engine Limits**
+ - Google API free tier is limited to 100 requests per day
+ - Other search engines generally do not have strict limits, but please use responsibly
+ - Frequent requests may cause temporary rate limiting
-```json
-{
- "mcpServers": {
- "cloudflare-search": {
- "command": "npx",
- "args": ["-y", "@yrobot/cf-search-mcp"],
- "env": {
- "CF_SEARCH_URL": "https://your-worker.workers.dev",
- "CF_SEARCH_TOKEN": "your-token-here"
- }
- }
- }
-}
-```
+3. **Timeout Settings**
+ - Default timeout per engine is 3 seconds
+ - Can be adjusted with `DEFAULT_TIMEOUT`
+ - Do not set it too high to avoid long overall response times
-**环境变量说明**：
+### 🔒 Security Configuration
-- `CF_SEARCH_URL`: Worker 部署地址（必填）
-- `CF_SEARCH_TOKEN`: 鉴权 Token（如果 Worker 配置了 TOKEN 则必填）
+#### Enable Authentication
-#### 2. 重启应用
+1. Configure the `TOKEN` environment variable to protect your service from abuse:
-保存配置后重启 Claude Code 或 Claude Desktop。
+- Configure `TOKEN` in `wrangler.toml`
+- Configure `TOKEN` in Cloudflare Worker Dashboard
-#### 3. 验证安装
-
-- 在 Claude Code 中运行 `/mcp` 命令，应该能看到 `cloudflare-search` 工具。
-- 或 使用 `claude mcp list`, 看到 `cloudflare-search: npx -y @yrobot/cf-search-mcp@latest - ✓ Connected` 说明配置成功
-
-### 使用示例
-
-```
-用 cloudflare-search 搜索 "Cloudflare Workers 最佳实践"
-```
-
-```
-用 cloudflare-search 搜索 "Next.js 14 新特性"
-```
-
-AI 会返回来自多个搜索引擎的聚合结果，包括标题、描述和链接。
-
-## 注意与提醒
-
-### 🚨 重要提示
-
-1. **使用自定义域名**
-
- - Cloudflare 默认的 `*.workers.dev` 域名在某些地区可能无法访问
- - **强烈建议**绑定自己的域名以获得更好的访问体验
- - 在 Worker 设置中点击 **Triggers** > **Add Custom Domain** 添加自定义域名
-
-2. **搜索引擎限制**
-
- - Google API 免费版每天限制 100 次请求
- - 其他搜索引擎一般没有严格限制，但请合理使用
- - 频繁请求可能导致被临时限制访问
-
-3. **超时设置**
- - 默认单个引擎超时 3 秒
- - 可通过环境变量 `DEFAULT_TIMEOUT` 调整
- - 建议不要设置过长，避免整体响应时间过长
-
-### 🔒 安全配置
-
-#### 启用鉴权
-
-1. 配置 `TOKEN` 环境变量 来保护你的服务不被滥用：
-
-- 利用 wrangler.toml 配置 TOKEN 环境变量
-- 通过 Cloudflare Worker Dashboard 配置 TOKEN 环境变量
-
-2. 在请求时传入 token：
+2. Pass token in requests:
```bash
-# 访问首页
+# Access homepage
https://$YOUR-DOMAIN?token=$YOUR-TOKEN
-# 使用 query/body 的 token 参数 请求 API
+# Request API with token parameter in query/body
curl "https://$YOUR-DOMAIN/search?q=cloudflare&token=$YOUR-TOKEN"
curl -X POST "https://$YOUR-DOMAIN/search" \
- -d "q=cloudflare" \
- -d "token=$YOUR-TOKEN"
+ -d "q=cloudflare" \
+ -d "token=$YOUR-TOKEN"
```
-## 常见问题
+## FAQ
-### Q: 为什么有些搜索引擎返回结果为空？
+### Q: Why do some search engines return empty results?
-A: 可能原因：
+A: Possible reasons:
-- 搜索引擎 API 临时不可用或响应超时
-- 搜索关键词没有相关结果
-- 搜索引擎限制了访问频率
-- Google 需要配置 API Key 才能使用
+- Search engine API is temporarily unavailable or timed out
+- No relevant results for the search keyword
+- Search engine has rate-limited access
+- Google requires API Key configuration before use
-可以查看返回的 `unresponsive_engines` 字段了解哪些引擎没有响应。
+You can check the `unresponsive_engines` field in the response to see which engines did not respond.
-### Q: 如何提高搜索速度？
+### Q: How can I improve search speed?
-A: 建议：
+A: Recommendations:
-- 减少启用的搜索引擎数量，只使用需要的引擎
-- 适当调整超时时间（`DEFAULT_TIMEOUT`）
+- Reduce the number of enabled search engines and only use the engines you need
+- Adjust timeout (`DEFAULT_TIMEOUT`) appropriately
-### Q: Bing 搜索为什么默认禁用？
+### Q: Why is Bing search disabled by default?
-A: Bing 搜索结果目前不够稳定，出现内容与搜索关联度低的情况。如需使用，可以在请求时手动指定：`engines=bing` 或修改 `envs.js` 中的 `DEFAULT_ENGINES`。
+A: Bing search results are currently not stable enough, and may return content with low relevance to the query. If needed, you can manually specify `engines=bing` in requests or modify `DEFAULT_ENGINES` in `envs.js`.
-### Q: 如何保护服务不被滥用？
+### Q: How can I protect the service from abuse?
-A: 建议配置 `TOKEN` 环境变量启用鉴权：
+A: It is recommended to configure the `TOKEN` environment variable to enable authentication:
-1. 在 `wrangler.toml` 中设置 `TOKEN = "your-random-token"`
-2. 或在 Cloudflare Dashboard 的 Environment Variables 中添加
-3. 配置后所有请求都需要提供有效的 token
+1. Set `TOKEN = "your-random-token"` in `wrangler.toml`
+2. Or add it in Environment Variables in Cloudflare Dashboard
+3. After configuration, all requests must provide a valid token
-鉴权失败会返回 401 错误
+Authentication failure returns a 401 error.
-## 免责声明
+## Disclaimer
-本项目仅供学习和研究使用，使用者需遵守以下规定：
+This project is for learning and research purposes only. Users must comply with the following:
-1. **合法使用** - 仅用于合法搜索需求，不得用于违法或侵权用途
-2. **服务条款** - 使用时需遵守 Cloudflare Workers 和各搜索引擎的服务条款
-3. **API 限制** - 遵守各搜索引擎 API 的使用限制和配额
-4. **责任自负** - 使用本服务产生的任何后果由使用者自行承担
-5. **商业用途** - 如需商业使用，请确保符合相关法律法规和服务条款
+1. **Lawful Use** - Only use for legal search purposes. Do not use for illegal or infringing activities
+2. **Terms of Service** - Comply with the terms of Cloudflare Workers and each search engine
+3. **API Limits** - Follow usage limits and quotas of each search engine API
+4. **Use at Your Own Risk** - Any consequences from using this service are the user's responsibility
+5. **Commercial Use** - For commercial use, ensure compliance with relevant laws, regulations, and service terms
-## 贡献
+## Contributing
-欢迎提交 Issue 和 Pull Request！
+Issues and Pull Requests are welcome!
-## 许可证
+## License
[GPL-3 License](LICENSE)
-## 相关链接
+## Related Links
-- [项目 GitHub](https://github.com/Yrobot/cloudflare-search)
-- [Cloudflare Workers 文档](https://developers.cloudflare.com/workers/)
+- [Project GitHub](https://github.com/Yrobot/cloudflare-search)
+- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
- [Google Custom Search API](https://developers.google.com/custom-search/v1/overview)
-## 支持一下
+## Support the Project
-如果这个项目对你有帮助，可以请作者喝杯咖啡 ☕
+If this project helps you, you can buy the author a coffee ☕
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..d1195ea
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,438 @@
+# Cloudflare Search
+
+[English](./README.md) | 中文
+
+> 基于 Cloudflare Workers 的聚合搜索 API 服务
+
+> 支持 **MCP (Model Context Protocol)**，让 AI 助手（OpenClaw、Claude Code、Codex、OpenCode）拥有实时联网搜索能力
+
+[](https://sink.proddig.com/cloudflare-search-github)
+
+## 特性
+
+- 🔍 **多引擎聚合** - 同时使用多个搜索引擎（Google、Brave、DuckDuckGo、Bing）
+- 🤖 **AI 增强 (MCP)** - 原生支持 Model Context Protocol，一键为 **OpenClaw** / **Claude Code** / **Codex** 添加搜索工具
+- ⚡ **并行搜索** - 所有搜索引擎同时请求，快速返回结果
+- 🛡️ **容错机制** - 单个引擎失败不影响其他引擎，自动标记无响应引擎
+- ⏱️ **超时控制** - 可配置请求超时时间，避免长时间等待
+- 🔒 **Token 鉴权** - 支持 Token 认证，保护服务不被滥用
+- 🌍 **CORS 支持** - 完整的跨域资源共享支持
+- 🎨 **Web 界面** - 提供简洁的搜索界面，方便测试
+- ⚡ **零成本运行** - Cloudflare Workers 免费版每天 10 万次请求
+
+## 页面展示
+
+
+
+## MCP 集成， 在 OpenClaw / Claude Code / AI Agent 中使用
+
+通过 MCP (Model Context Protocol) 让 AI 助手直接调用你的搜索服务，获取实时搜索结果。
+
+### 安装配置
+
+
+
+#### 1. 部署服务
+
+先按照文档 [部署 Cloudflare Search](#安装方式)
+
+#### 2. 添加 MCP 服务器配置
+
+编辑配置文件（[配置指南](https://modelcontextprotocol.io/quickstart/user)）：
+
+- **OpenClaw**: `~/.openclaw/openclaw.json`
+- **Claude Code**: `~/.claude/config.json` / `~/.claude.json`
+- **Claude Desktop macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Claude Desktop Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+ "mcpServers": {
+ "cloudflare-search": {
+ "command": "npx",
+ "args": ["-y", "@yrobot/cf-search-mcp"],
+ "env": {
+ "CF_SEARCH_URL": "https://your-worker.workers.dev",
+ "CF_SEARCH_TOKEN": "your-token-here"
+ }
+ }
+ }
+}
+```
+
+**环境变量说明**：
+
+- `CF_SEARCH_URL`: Worker 部署地址（必填）
+- `CF_SEARCH_TOKEN`: 鉴权 Token（如果 Worker 配置了 TOKEN 则必填）
+
+#### 3. 验证安装
+
+- **OpenClaw**: `openclaw gateway restart` + `openclaw mcp list` 能看到 `cloudflare-search`
+- **Claude Code**:
+ - 在 Claude Code 中运行 `/mcp` 命令，应该能看到 `cloudflare-search` 工具。
+ - 或 使用 `claude mcp list`, 看到 `cloudflare-search: npx -y @yrobot/cf-search-mcp@latest - ✓ Connected` 说明配置成功
+
+## 安装方式
+
+### 方式一：一键部署（推荐）
+
+点击上方 "Deploy to Cloudflare Workers" 按钮，按照提示完成部署。
+
+### 方式二：使用 Wrangler CLI
+
+```bash
+# 1. 安装 Wrangler
+npm install -g wrangler
+
+# 2. 登录 Cloudflare
+wrangler login
+
+# 3. 克隆仓库
+git clone https://github.com/Yrobot/cloudflare-search.git
+cd cloudflare-search
+
+# 4. 部署
+wrangler deploy
+```
+
+### 方式三：使用 Cloudflare Dashboard
+
+1. 登录 [Cloudflare Dashboard](https://dash.cloudflare.com/)
+2. 进入 **Workers & Pages**
+3. 点击 **Create Application** > **Create Worker**
+4. 点击 **Upload** 上传本地代码文件夹
+ - 选择克隆的 `cloudflare-search` 文件夹
+ - 或者手动复制 `worker.js`、`envs.js`、`utils/` 等文件
+5. 点击 **Save and Deploy**
+
+### 获取访问地址
+
+部署成功后，你会获得一个 Worker URL：
+
+```
+https://your-worker-name.your-subdomain.workers.dev
+```
+
+**注意**：这个自带的域名在某些区域可能无法直接访问，建议绑定自己的域名使用。
+
+## 使用方式
+
+### 方式 1: Web 界面
+
+直接访问你的 Worker URL，在网页界面输入搜索关键词：
+
+```
+https://$YOUR-DOMAIN/
+```
+
+### 方式 2: API 请求（GET）
+
+使用查询参数进行搜索：
+
+```bash
+# 基本搜索
+curl "https://$YOUR-DOMAIN/search?q=cloudflare"
+
+# 指定搜索引擎
+curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave"
+
+# 使用 token 鉴权（如果配置了 TOKEN 环境变量）
+curl "https://$YOUR-DOMAIN/search?q=cloudflare&token=$YOUR-TOKEN"
+```
+
+### 方式 3: API 请求（POST）
+
+通过 POST 表单提交搜索：
+
+```bash
+curl -X POST "https://$YOUR-DOMAIN/search" \
+ -d "q=cloudflare" \
+ -d "engines=google,brave"
+ -d "token=$YOUR-TOKEN" # 如果配置了 TOKEN 环境变量
+```
+
+## API 接口说明
+
+### `/search` 接口
+
+用于执行搜索查询并返回聚合结果。
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 | 示例 |
+| ------------- | -------- | ------ | ----------------------------------------- | -------------- |
+| `q` / `query` | `string` | yes | 搜索关键词 | `cloudflare` |
+| `engines` | `string` | no | 指定搜索引擎，多个用逗号分隔 | `google,brave` |
+| `token` | `string` | no/yse | 访问令牌（当配置了 TOKEN 环境变量时必填） | `$YOUR-TOKEN` |
+
+**支持的搜索引擎**：
+
+- `google` - Google 搜索（需要配置 API Key）
+- `brave` - Brave 搜索
+- `duckduckgo` - DuckDuckGo 搜索
+- `bing` - Bing 搜索
+
+#### 返回值
+
+```typescript
+{
+ query: string; // 搜索关键词
+ number_of_results: number; // 结果总数
+ enabled_engines: string[]; // 启用的搜索引擎列表
+ unresponsive_engines: string[]; // 无响应的搜索引擎列表
+ results: Array<{
+ title: string; // 结果标题
+ description: string; // 结果描述
+ url: string; // 结果链接
+ engine: string; // 来源引擎
+ }>;
+}
+```
+
+#### 请求示例
+
+```bash
+# GET 请求
+curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave"
+
+# POST 请求
+curl -X POST "https://$YOUR-DOMAIN/search" \
+ -H "Content-Type: application/x-www-form-urlencoded" \
+ -d "q=cloudflare&engines=google,brave"
+```
+
+#### 响应示例
+
+```json
+{
+ "query": "cloudflare",
+ "number_of_results": 15,
+ "enabled_engines": ["google", "brave", "duckduckgo"],
+ "unresponsive_engines": [],
+ "results": [
+ {
+ "title": "Cloudflare - The Web Performance & Security Company",
+ "description": "Cloudflare is on a mission to help build a better Internet...",
+ "url": "https://www.cloudflare.com/",
+ "engine": "google"
+ },
+ {
+ "title": "Cloudflare Workers",
+ "description": "Deploy serverless code instantly across the globe...",
+ "url": "https://workers.cloudflare.com/",
+ "engine": "brave"
+ }
+ ]
+}
+```
+
+## 搜索引擎说明
+
+### 支持的搜索引擎
+
+| 引擎 | 说明 | 是否需要配置 | 默认启用 |
+| -------------- | ------------------------ | ----------------------------- | --------------- |
+| **Google** | Google Custom Search API | 需要 GOOGLE_API_KEY GOOGLE_CX | yes |
+| **Brave** | Brave Search API | - | yes |
+| **DuckDuckGo** | DuckDuckGo 即时答案 API | - | yes |
+| **Bing** | Bing 搜索 | - | no (结果不稳定) |
+
+### 基本工作方案
+
+1. **并行请求**：所有启用的搜索引擎同时发起请求，提高响应速度
+2. **超时控制**：单个引擎超时不影响其他引擎，默认 3 秒超时
+3. **结果聚合**：将所有成功返回的结果合并，标记来源引擎
+4. **容错处理**：记录无响应的引擎，返回部分结果而不是完全失败
+
+## 环境变量配置
+
+### 环境变量说明
+
+| 变量名 | 类型 | 默认值 | 说明 |
+| ----------------- | -------- | -------- | ------------------------------------------------- |
+| `DEFAULT_TIMEOUT` | `string` | `"3000"` | 单个搜索引擎的超时时间（毫秒） |
+| `GOOGLE_API_KEY` | `string` | `null` | https://console.cloud.google.com/apis/credentials |
+| `GOOGLE_CX` | `string` | `null` | https://programmablesearchengine.google.com/ |
+| `TOKEN` | `string` | `null` | 访问令牌，配置后启用鉴权，保护服务不被滥用 |
+
+**注意**：
+
+- Google Custom Search API 免费版每天限制 100 次请求
+- `TOKEN` 配置后，所有请求都需要提供有效的 token
+
+### 配置方式
+
+#### 方式 1: wrangler.toml 文件
+
+编辑 `wrangler.toml` 文件中的 `[vars]` 部分：
+
+```toml
+[vars]
+GOOGLE_API_KEY = "your-google-api-key"
+GOOGLE_CX = "your-google-custom-search-cx"
+DEFAULT_TIMEOUT = "3000"
+TOKEN = "your-secret-token-here"
+```
+
+#### 方式 2: Cloudflare Dashboard
+
+1. 进入 Worker 设置页面
+2. 找到 **Environment Variables** 部分
+3. 添加变量并保存
+
+## 使用场景
+
+### 1. 聚合搜索服务
+
+构建自己的搜索聚合 API，整合多个搜索引擎结果：
+
+```javascript
+const response = await fetch(
+ "https://$YOUR-DOMAIN/search?q=javascript&engines=google,brave",
+);
+const data = await response.json();
+console.log(`找到 ${data.number_of_results} 个结果`);
+```
+
+### 2. 前端搜索功能
+
+为网站或应用添加搜索功能：
+
+```javascript
+async function search(query) {
+ const response = await fetch(
+ `https://$YOUR-DOMAIN/search?q=${encodeURIComponent(query)}`,
+ );
+ const data = await response.json();
+ return data.results;
+}
+```
+
+### 3. 数据采集与分析
+
+收集多个搜索引擎的结果进行对比分析：
+
+```javascript
+const engines = ["google", "brave", "duckduckgo"];
+const results = await fetch(
+ `https://$YOUR-DOMAIN/search?q=AI&engines=${engines.join(",")}`,
+);
+const data = await results.json();
+
+// 按引擎分组
+const byEngine = data.results.reduce((acc, result) => {
+ acc[result.engine] = acc[result.engine] || [];
+ acc[result.engine].push(result);
+ return acc;
+}, {});
+```
+
+## MCP 集成
+
+通过 MCP (Model Context Protocol) 让 AI 助手直接调用你的搜索服务，获取实时搜索结果。
+
+## 注意与提醒
+
+### 🚨 重要提示
+
+1. **使用自定义域名**
+ - Cloudflare 默认的 `*.workers.dev` 域名在某些地区可能无法访问
+ - **强烈建议**绑定自己的域名以获得更好的访问体验
+ - 在 Worker 设置中点击 **Triggers** > **Add Custom Domain** 添加自定义域名
+
+2. **搜索引擎限制**
+ - Google API 免费版每天限制 100 次请求
+ - 其他搜索引擎一般没有严格限制，但请合理使用
+ - 频繁请求可能导致被临时限制访问
+
+3. **超时设置**
+ - 默认单个引擎超时 3 秒
+ - 可通过环境变量 `DEFAULT_TIMEOUT` 调整
+ - 建议不要设置过长，避免整体响应时间过长
+
+### 🔒 安全配置
+
+#### 启用鉴权
+
+1. 配置 `TOKEN` 环境变量 来保护你的服务不被滥用：
+
+- 利用 wrangler.toml 配置 TOKEN 环境变量
+- 通过 Cloudflare Worker Dashboard 配置 TOKEN 环境变量
+
+2. 在请求时传入 token：
+
+```bash
+# 访问首页
+https://$YOUR-DOMAIN?token=$YOUR-TOKEN
+
+# 使用 query/body 的 token 参数 请求 API
+curl "https://$YOUR-DOMAIN/search?q=cloudflare&token=$YOUR-TOKEN"
+
+curl -X POST "https://$YOUR-DOMAIN/search" \
+ -d "q=cloudflare" \
+ -d "token=$YOUR-TOKEN"
+```
+
+## 常见问题
+
+### Q: 为什么有些搜索引擎返回结果为空？
+
+A: 可能原因：
+
+- 搜索引擎 API 临时不可用或响应超时
+- 搜索关键词没有相关结果
+- 搜索引擎限制了访问频率
+- Google 需要配置 API Key 才能使用
+
+可以查看返回的 `unresponsive_engines` 字段了解哪些引擎没有响应。
+
+### Q: 如何提高搜索速度？
+
+A: 建议：
+
+- 减少启用的搜索引擎数量，只使用需要的引擎
+- 适当调整超时时间（`DEFAULT_TIMEOUT`）
+
+### Q: Bing 搜索为什么默认禁用？
+
+A: Bing 搜索结果目前不够稳定，出现内容与搜索关联度低的情况。如需使用，可以在请求时手动指定：`engines=bing` 或修改 `envs.js` 中的 `DEFAULT_ENGINES`。
+
+### Q: 如何保护服务不被滥用？
+
+A: 建议配置 `TOKEN` 环境变量启用鉴权：
+
+1. 在 `wrangler.toml` 中设置 `TOKEN = "your-random-token"`
+2. 或在 Cloudflare Dashboard 的 Environment Variables 中添加
+3. 配置后所有请求都需要提供有效的 token
+
+鉴权失败会返回 401 错误
+
+## 免责声明
+
+本项目仅供学习和研究使用，使用者需遵守以下规定：
+
+1. **合法使用** - 仅用于合法搜索需求，不得用于违法或侵权用途
+2. **服务条款** - 使用时需遵守 Cloudflare Workers 和各搜索引擎的服务条款
+3. **API 限制** - 遵守各搜索引擎 API 的使用限制和配额
+4. **责任自负** - 使用本服务产生的任何后果由使用者自行承担
+5. **商业用途** - 如需商业使用，请确保符合相关法律法规和服务条款
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+[GPL-3 License](LICENSE)
+
+## 相关链接
+
+- [项目 GitHub](https://github.com/Yrobot/cloudflare-search)
+- [Cloudflare Workers 文档](https://developers.cloudflare.com/workers/)
+- [Google Custom Search API](https://developers.google.com/custom-search/v1/overview)
+
+## 支持一下
+
+如果这个项目对你有帮助，可以请作者喝杯咖啡 ☕
+
+
diff --git a/mcp/cf-search-mcp.js b/mcp/cf-search-mcp.js
index b47925f..eda0b92 100644
--- a/mcp/cf-search-mcp.js
+++ b/mcp/cf-search-mcp.js
@@ -24,7 +24,9 @@ const CF_SEARCH_TOKEN = process.env.CF_SEARCH_TOKEN;
if (!CF_SEARCH_URL) {
console.error("Error: CF_SEARCH_URL environment variable is required");
- console.error("Example: export CF_SEARCH_URL=https://your-worker.workers.dev");
+ console.error(
+ "Example: export CF_SEARCH_URL=https://your-worker.workers.dev",
+ );
process.exit(1);
}
@@ -64,46 +66,57 @@ async function searchAPI(query, engines = null) {
const server = new Server(
{
name: "cloudflare-search",
- version: "1.0.0",
+ version: "1.1.0",
},
{
capabilities: {
tools: {},
},
- }
+ },
);
+const SEARCH_INPUT_SCHEMA = {
+ type: "object",
+ properties: {
+ query: {
+ type: "string",
+ description: "The search query string",
+ },
+ engines: {
+ type: "array",
+ items: {
+ type: "string",
+ enum: ["google", "brave", "duckduckgo", "bing"],
+ },
+ description:
+ "Optional: Array of search engines to use. If not specified, uses default engines. " +
+ "Available engines: google, brave, duckduckgo, bing",
+ },
+ },
+ required: ["query"],
+};
+
/**
* Handler for listing available tools
*/
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
+ {
+ name: "web_search",
+ description:
+ "Search the web for current information, news, or any topic. " +
+ "Uses multiple engines (Brave, DuckDuckGo, Google, Bing) simultaneously " +
+ "and returns aggregated results with source URLs. " +
+ "Use this when you need real-time information not in your training data. ",
+ inputSchema: SEARCH_INPUT_SCHEMA,
+ },
{
name: "search",
description:
"Search across multiple search engines (Google, Brave, DuckDuckGo, Bing) and return aggregated results. " +
"This tool provides comprehensive search results from multiple sources, with source attribution for each result.",
- inputSchema: {
- type: "object",
- properties: {
- query: {
- type: "string",
- description: "The search query string",
- },
- engines: {
- type: "array",
- items: {
- type: "string",
- enum: ["google", "brave", "duckduckgo", "bing"],
- },
- description:
- "Optional: Array of search engines to use. If not specified, uses default engines. " +
- "Available engines: google, brave, duckduckgo, bing",
- },
- },
- required: ["query"],
- },
+ inputSchema: SEARCH_INPUT_SCHEMA,
},
],
};
@@ -113,7 +126,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
* Handler for tool execution
*/
server.setRequestHandler(CallToolRequestSchema, async (request) => {
- if (request.params.name !== "search") {
+ if (
+ request.params.name !== "search" &&
+ request.params.name !== "web_search"
+ ) {
throw new Error(`Unknown tool: ${request.params.name}`);
}
diff --git a/package.json b/package.json
index ea06d23..3750c18 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@yrobot/cf-search-mcp",
- "version": "1.0.0",
+ "version": "1.1.0",
"description": "MCP server for Cloudflare Search API - Aggregated search across multiple engines",
"type": "module",
"publishConfig": {
@@ -16,8 +16,15 @@
"keywords": [
"mcp",
"search",
+ "web-search",
"cloudflare",
- "api",
+ "cloudflare-workers",
+ "self-hosted",
+ "ai-agent",
+ "openclaw",
+ "free-search",
+ "privacy",
+ "aggregated-search",
"google",
"brave",
"duckduckgo",