内容
# Palena 网络搜索 MCP
**适用于 AI 的企业级网络搜索，内置合规边界。**
[](LICENSE)
[](https://go.dev/)
[](https://modelcontextprotocol.io/)
[](https://opentelemetry.io/)
Palena 是一个单二进制文件的 MCP 服务器，它将嘈杂的公共网络转换为 LLM-ready 上下文 — **搜索、抓取、去 PII、重新排序和哈希链，以进行审计** — 这样您的代理可以浏览而不会让每个合规官员都绊倒。
为 fintech、healthtech 和 govtech 团队构建，这些团队不能将原始的第三方 HTML 直接发送到基础模型，但仍然需要他们的 AI 具有来自实时互联网的新鲜、引用和可复制的知识。
> *Palena* — 夏威夷语中的 *边界、限制、边境*。
---
## 为什么选择 Palena
| 问题 | 大多数“网络搜索”工具的做法 | Palena 的做法 |
|---|---|---|
| 原始页面泄漏 PII 进入提示 | 直接发送 HTML | 在 LLM 看到之前进行 Presidio 审计/编辑/阻止 |
| 受机器人保护的网站返回为空 | 静默失败 | 分级 L0→L1→L2 升级（可读性 → 无头 → 隐身 + 代理） |
| “我们抓取了这个”没有凭证 | 没有凭证 | 每个文档的三阶段 SHA-256 哈希链 |
| 结果由通用搜索引擎排名 | 信任前 10 名 | 可插拔的重新排序器（KServe GPU、FlashRank CPU、RankLLM 或无） |
| 合规性只显示演示 | 希望最好 | 域名允许/阻止列表、robots.txt 执行、每个域的速率限制、每个跨度的 OTel 跟踪 |
---
## 流程
```
MCP 工具/调用 web_search
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 1. 搜索 SearXNG 元搜索引擎 │
│ 查询扩展 · 引擎路由 · 去重 │
├──────────────────────────────────────────────────────────────┤
│ 2. 策略 域名允许/阻止 · robots.txt · 速率限制 │
├──────────────────────────────────────────────────────────────┤
│ 3. 抓取 L0 HTTP + 可读性 （快速路径） │
│ L1 Playwright 无头 （需要 JS） │
│ L2 Playwright + 隐身/代理（反机器人） │
├──────────────────────────────────────────────────────────────┤
│ 4. PII Microsoft Presidio · 审计/编辑/阻止 │
├──────────────────────────────────────────────────────────────┤
│ 5. 重新排序 FlashRank · KServe 跨编码器 · RankLLM │
├──────────────────────────────────────────────────────────────┤
│ 6. 格式化 markdown · 引用 · SHA-256 凭证 │
└──────────────────────────────────────────────────────────────┘
│
▼
MCP tool_result
```
每个阶段都是一个 OpenTelemetry 跨度。每个文档都经过三个哈希（原始 HTML → 提取的 markdown → 最终交付的内容）。审计轨迹可以直接发送到 ClickHouse。
---
## 实时示例
MCP 服务器实时输出，回答 *"2026 最新 AI 热点话题"*（类别：`新闻`）：
```json
{
"query": "latest AI hot topics 2026",
"result_count": 3,
"reranker_used": "flashrank",
"pii_mode": "audit",
"pii_checked": true,
"search_engines": ["google news", "duckduckgo", "bing news"],
"total_duration_ms": 4414,
"results": [
{ "title": "OpenClaw Exposes the Real Cybersecurity Risks of Agentic AI",
"score": 0.984, "scraper_level": 0,
"content_hash": "c3b4d690…" },
{ "title": "Comprehensive AI Conference List for 2026: Dates, Locations, and Keynotes",
"score": 0.973, "scraper_level": 0,
"content_hash": "7af1205e…" },
{ "title": "Can AI infrastructure costs be a value driver? — Oracle AI World 2026",
"score": 0.002, "scraper_level": 0,
"content_hash": "9e48c311…" }
]
}
```
注意 FlashRank 如何将实质性内容推到顶部（0.98 / 0.97）并降低包含正确关键字的供应商会议稿的排名（0.002）- 信号是标准 SearXNG 排名无法实现的。
---
## 快速开始
### 完整栈（所有边车）
```bash
docker compose -f deploy/docker-compose.yml up --build
```
启动 Palena + SearXNG + Presidio Analyzer + Presidio Anonymizer + Playwright + FlashRank。
### 最小化（仅 L0 抓取）
```bash
docker compose -f deploy/docker-compose.minimal.yml up --build
```
Palena + SearXNG 仅。~200 MB 镜像，无浏览器，无 PII，无重新排序。
### 服务器健康测试
```bash
# 边车健康
curl http://localhost:8080/health
# → {"status":"ok","sidecars":{"searxng":"ok","presidio-analyzer":"ok",...}}
# 列出通过 MCP Streamable HTTP 公开的工具
SESS=$(curl -sS -X POST http://localhost:8080/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}' \
-D - -o /dev/null | awk '/Mcp-Session-Id/ {print $2}' | tr -d '\r')
curl -sS -X POST http://localhost:8080/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H "Mcp-Session-Id: $SESS" \
-d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
curl -sS -X POST http://localhost:8080/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H "Mcp-Session-Id: $SESS" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```
---
## MCP 客户端集成
### LibreChat
```yaml
# librechat.yaml
mcpServers:
palena:
type: streamableHttp # 或：sse
url: http://palena:8080/mcp
```
### Claude Desktop
```json
{
"mcpServers": {
"palena": { "url": "http://localhost:8080/sse" }
}
}
```
### Cursor / Windsurf / 自定义代理
任何 MCP 兼容的客户端都可以使用 - 连接到 `/sse`（旧事件流）或 `/mcp`（Streamable HTTP）。
---
## `web_search` 工具
```json
{
"name": "web_search",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string", "description": "搜索查询" },
"category": { "type": "string", "description": "general | news | code | science （默认为 general）" },
"language": { "type": "string", "description": "ISO 代码 — en, de, fr… （默认为 en）" },
"timeRange": { "type": "string", "description": "day | week | month | year" },
"maxResults": { "type": "integer", "description": "1–20 （默认为 5）" }
},
"required": ["query"]
}
}
```
响应格式化为 markdown，包含编号结果、相关性评分、来源引用和结构化元数据（PII 状态、重新排序器、命中引擎、总延迟）。
---
## 配置
从注释示例开始：
```bash
cp config/palena.example.yaml config/palena.yaml
```
| 部分 | 控制 | 关键环境变量 |
|---|---|---|
| `search` | SearXNG URL、每个类别的引擎、默认语言 | `PALENA_SEARCH_SEARXNG_URL` |
| `scraper` | 并发性、超时、Playwright WS 端点、代理池 | `PALENA_SCRAPER_PLAYWRIGHT_ENDPOINT` |
| `pii` | 模式（审计/编辑/阻止）、Presidio URL、实体 | `PALENA_PII_MODE` |
| `reranker` | 提供者（`kserve` / `flashrank` / `rankllm` / `none`） | `PALENA_RERANKER_PROVIDER` |
| `policy` | 域名允许/阻止列表、robots.txt 缓存、速率限制 | `PALENA_POLICY_DOMAIN_MODE` |
| `provenance` | 哈希链、ClickHouse 导出 | `PALENA_PROVENANCE_ENABLED` |
| `otel` | 跟踪 + 指标导出器 | `PALENA_OTEL_ENABLED` |
完整注释参考：[`config/palena.example.yaml`](config/palena.example.yaml) · 深入了解：[配置指南](docs/configuration.md)。
---
## 边车矩阵
Palena 是一个 Go 协调器。每个外部功能都作为自己的容器运行，除 SearXNG 外都是可选的。
| 边车 | 镜像 | 协议 | 必需 | 目的 |
|---|---|---|---|---|
| SearXNG | `searxng/searxng` | HTTP JSON | **是** | 元搜索引擎聚合 |
| Presidio Analyzer | `mcr.microsoft.com/presidio-analyzer` | HTTP JSON | 否 | PII 实体检测 |
| Presidio Anonymizer | `mcr.microsoft.com/presidio-anonymizer` | HTTP JSON | 否 | PII 屏蔽/替换 |
| Playwright | `mcr.microsoft.com/playwright` | Playwright WS | 否 | JS 渲染页面提取（L1/L2） |
| FlashRank | Flask + ONNX（捆绑） | HTTP JSON | 否 | CPU 跨编码器重新排序 |
| KServe | 您自己的 InferenceService | HTTP JSON | 否 | GPU 跨编码器重新排序 |
缺少的边车会触发**优雅降级**，而不是故障 - L1/L2 禁用，PII 报告为“未检查”，重新排序器恢复为搜索引擎顺序。
### 部署配置文件
| 配置文件 | 组件 | 占用空间 |
|---|---|---|
| **最小化** | Palena + SearXNG | ~200 MB |
| **标准** | + Presidio + Playwright + FlashRank | ~2–3 GB |
| **企业** | + KServe GPU 重新排序器（例如 `mxbai-rerank`） | 可变（GPU） |
### Helm（Kubernetes / OpenShift）
```bash
# 标准
helm install palena deploy/helm/palena/
# 最小化 - 禁用所有可选边车
helm install palena deploy/helm/palena/ \
--set presidio.enabled=false \
--set playwright.enabled=false \
--set flashrank.enabled=false
# 使用您自己的 GPU 重新排序器
helm install palena deploy/helm/palena/ \
--set reranker.provider=kserve \
--set reranker.endpoint=http://mxbai-rerank.kserve.svc:8080
```
---
## HTTP 端点
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/sse` | MCP SSE 传输（旧事件流） |
| `POST` | `/mcp` | MCP Streamable HTTP 传输 |
| `GET` | `/health` | 边车可达性探测 |
| `GET` | `/metrics` | Prometheus 指标（启用 OTel 指标时） |
---
## 项目布局
```
palena-websearch-mcp/
├── cmd/palena/ # 二进制入口点，配置 + 服务器线路
├── internal/
│ ├── config/ # YAML 解析，验证，环境变量覆盖
│ ├── search/ # SearXNG 客户端，查询扩展，去重
│ ├── scraper/ # L0 可读性 · L1/L2 Playwright · 隐身 · 代理池
│ ├── pii/ # Presidio 客户端，策略模式，PII 审计记录
│ ├── reranker/ # 可插拔接口 · KServe · FlashRank · RankLLM · no-op
│ ├── policy/ # 域名过滤，robots.txt，每域速率限制
│ ├── output/ # Markdown 格式化，凭证哈希链
│ ├── transport/ # MCP SSE + Streamable HTTP，工具处理程序
│ └── otel/ # 跟踪 + 指标设置
├── config/ # 默认 + 注释示例 YAML
├── deploy/ # Dockerfile，Compose（完整 + 最小化），Helm 图表
└── docs/ # 用户文档
```
---
## 文档
完整用户文档位于 [`docs/`](docs/README.md)。
| 主题 | 阅读位置 |
|---|---|
| **开始这里** | [快速入门](docs/getting-started.md) · [概念](docs/concepts.md) · [常见问题](docs/faq.md) |
| **使用服务器** | [工具参考](docs/tool-reference.md) · [集成](docs/integrations.md) · [配置](docs/configuration.md) |
| **管道阶段** | [抓取](docs/scraping.md) · [PII 和合规性](docs/pii-and-compliance.md) · [重新排序](docs/reranking.md) · [凭证](docs/provenance.md) |
| **在生产中运行** | [部署](docs/deployment.md) · [可观察性](docs/observability.md) |
---
## 技术栈
- **核心：** Go 1.26+，单个静态二进制文件
- **搜索：** [SearXNG](https://github.com/searxng/searxng)（自托管元搜索引擎）
- **提取：** [`go-shiori/go-readability`](https://github.com/go-shiori/go-readability)（L0），[`playwright-community/playwright-go`](https://github.com/playwright-community/playwright-go) 对抗 Microsoft 的官方 Playwright 镜像（L1/L2）
- **PII：** Microsoft [Presidio](https://microsoft.github.io/presidio/) Analyzer + Anonymizer
- **重新排序：** Mixedbread `mxbai-rerank` 通过 KServe · [FlashRank](https://github.com/PrithivirajDamodaran/FlashRank) ONNX/CPU · RankLLM 针对任何推理端点
- **可观察性：** [OpenTelemetry](https://opentelemetry.io/) 跟踪 + Prometheus 兼容的指标
- **传输：** MCP SSE，MCP Streamable HTTP
- **配置：** YAML + 环境变量覆盖
- **部署：** Docker Compose（开发），Helm 图表（Kubernetes / OpenShift）
---
## License
Copyright © 2026 bitkaio LLC.
在 [Apache License, Version 2.0](LICENSE) 许可下授权。你可以根据该许可证的条款使用、修改和重新分发 Palena。对于商业支持、自定义重新排序模型或生产 SLA，请联系 bitkaio LLC。
