内容
# 搜索MCP
[](LICENSE)
[](https://github.com/skyphusion-labs/search-mcp/actions/workflows/typecheck.yml)
[](https://github.com/skyphusion-labs/search-mcp/actions/workflows/ci.yml)
开源工具包，适用于 [Cloudflare AI 搜索](https://developers.cloudflare.com/ai-search/):
1. **MCP 工作器** (`src/mcp.ts`) -- 带有 `search` 工具的 bearer-gated 流式 HTTP MCP，适用于代理。
2. **查询工作器** (`src/index.ts`) -- 带 CORS + Turnstile + 速率限制的 `POST /ask`，为浏览器小部件流式传输答案。
3. **语料库同步** (`scripts/sync.mjs`, `scripts/sync-runner.mjs`) -- 跟踪 Git 的源代码到 R2，并进行扩展映射，以便 TypeScript、Dockerfile 和其他文本 AI 搜索否则会跳过索引。
```
git 仓库 -> sync.mjs -> R2 存储桶 -> AI 搜索实例 -> /ask + /mcp
```
## 安装（npm）
语料库同步 CLI 和询问小部件资产作为 **`@skyphusion/search-mcp`** 发布在 npm 上（无作用域名称 `search-mcp` 被另一个项目占用）。
```sh
npm install @skyphusion/search-mcp
# 或在不安装的情况下运行：
npx --package=@skyphusion/search-mcp search-mcp-sync corpus --dry-run
```
| 命令 | 角色 |
| --- | --- |
| `search-mcp-sync` | 将 Git 跟踪的语料库文件上传到 R2 以获取一个目标 |
| `search-mcp-sync-run` | 克隆/获取仓库，同步所有目标，可选重新索引 |
将 `targets.json` 放在您的项目根目录中（从 `node_modules/@skyphusion/search-mcp/scripts/targets.json.example` 复制）或设置 `SEARCH_MCP_TARGETS`。克隆根目录默认为当前工作目录；使用 `SYNC_REPO_ROOT` 覆盖。
安装后小部件资产：
```sh
cp node_modules/@skyphusion/search-mcp/public/ask-widget.{js,css} ./docs/
```
工作器（`src/`）从 Git 克隆中部署；参见 [docs/DEPLOY.md](docs/DEPLOY.md)。
## 快速开始（从源代码）
```sh
npm install
cp wrangler.toml.example wrangler.toml
cp wrangler.mcp.toml.example wrangler.mcp.toml
cp scripts/targets.json.example scripts/targets.json
# 为您的账户、实例、存储桶和仓库编辑这三个文件
npm run typecheck
npm test
```
配置 R2 + AI 搜索，同步您的语料库，部署两个工作器。逐步指南： [docs/DEPLOY.md](docs/DEPLOY.md)。
## Skyphusion 生产环境
此仓库是 Skyphusion AI 搜索（`search.vivijure.com`，`search-internal.vivijure.com`）的生产环境。配置在部署/同步时从 GitHub Actions 机密中生成；不要提交 `wrangler.toml`、`wrangler.mcp.toml` 或 `scripts/targets.json`。
- [操作手册](docs/skyphusion/OPERATOR.md) -- 机密、拓扑、引导
- [切换记录（2026-07-08）](docs/skyphusion/CUTOVER.md) -- 迁移历史、故障日志、存档步骤
## 工作器
| 工作器 | 入口 | 端点 | 身份验证 |
| --- | --- | --- | --- |
| 查询 | `wrangler.toml` | `POST /ask`，`GET /health` | Turnstile（可选）+ CORS 允许列表 |
| MCP | `wrangler.mcp.toml` | `POST /mcp`，`GET /health` | `Authorization: Bearer`（失败关闭） |
分别部署，以便浏览器流量和代理流量可以绑定不同的 AI 搜索实例（如果需要）。
```sh
npm run deploy # 查询工作器
npm run deploy:mcp # MCP 工作器
wrangler secret put MCP_TOKEN -c wrangler.mcp.toml
wrangler secret put TURNSTILE_SECRET # 可选；未设置时跳过验证
```
### MCP 客户端连接
```json
{
"mcpServers": {
"search-mcp": {
"type": "http",
"url": "https://您的MCP主机/mcp",
"headers": { "Authorization": "Bearer 您的令牌" }
}
}
}
```
`MCP_TOKEN` 接受单个令牌或逗号分隔的 `name=token` 对，用于日志中的每个消费者属性。
## 语料库同步
```sh
export R2_ACCESS_KEY_ID=... R2_SECRET_ACCESS_KEY=... CLOUDFLARE_ACCOUNT_ID=...
export CORPUS_GIT_ORG=your-org GITHUB_TOKEN=... # 用于 sync-runner 克隆身份验证
npm run sync:dry # 计划上传默认的 `corpus` 目标
npm run sync # 上传 + 清除
npm run sync:run # 隔离克隆根，同步所有目标，可选重新索引
```
同步映射非原生扩展（`.ts`、`.tsx`、无扩展的 `Dockerfile`、`.service` 等）到 `.txt` 键，以便 AI 搜索索引它们。参见 `scripts/sync-ingest.mjs`。
如果您将目标命名为 `public`，可选边界检查会拒绝与 `restrictedRepos` 重叠，并可以在上传前验证 GitHub 仓库可见性。
## 询问小部件
将 `public/ask-widget.js` 和 `public/ask-widget.css` 复制到您的文档站点：
```html
<div id="docs-ask"></div>
<script defer src="/ask-widget.js"
data-endpoint="https://search.example.com/ask"
data-target="#docs-ask"
data-label="询问文档"
data-sitekey="您的TURNSTILE_SITEKEY"></script>
```
## 本项目适用对象
构建文档搜索、代理工具或内部知识库的运维人员，基于 [Cloudflare AI 搜索](https://developers.cloudflare.com/ai-search/) 搭配 MCP 和浏览器小部件。
## 链接
- **部署指南：** [docs/DEPLOY.md](docs/DEPLOY.md)
- **Skyphusion 实验室：** https://skyphusion.org · **组织：** https://github.com/skyphusion-labs
- **相关项目：** [vivijure](https://github.com/skyphusion-labs/vivijure)， [postern](https://github.com/skyphusion-labs/postern)
## 许可证
AGPL-3.0-only。参见 [LICENSE](LICENSE)。
## 社区
- [贡献](CONTRIBUTING.md)
- [安全策略](SECURITY.md)
- [行为准则](CODE_OF_CONDUCT.md)
