内容
<p align="center">
<img src="assets/logo.png" alt="Scour" width="150" height="150">
</p>
<h1 align="center">Scour</h1>
<p align="center">
<strong>面向Agent的并发网络搜索与全文研究工具</strong><br>
基于Amazon Bedrock AgentCore Web Search — CLI · MCP服务器 · REST，全都通过本地AWS IAM/SigV4。
</p>
<p align="center">
<a href="https://github.com/neosun100/scour/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/neosun100/scour/actions/workflows/ci.yml/badge.svg"></a>
<a href="LICENSE"><img alt="License: MIT-0" src="https://img.shields.io/badge/License-MIT--0-blue.svg"></a>
<img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-3776AB.svg?logo=python&logoColor=white">
<img alt="Tests: 47 passing" src="https://img.shields.io/badge/tests-47%20passing-brightgreen.svg">
<img alt="MCP compatible" src="https://img.shields.io/badge/MCP-compatible-5eead4.svg">
<img alt="AWS Bedrock AgentCore" src="https://img.shields.io/badge/AWS-Bedrock%20AgentCore-FF9900.svg?logo=amazonaws&logoColor=white">
<img alt="Region us-east-1" src="https://img.shields.io/badge/region-us--east--1-232F3E.svg">
</p>
---
**Scour** 将单个受管理的 **Amazon Bedrock AgentCore Web Search** 工具转换为一个完整的Agent工具包。Scour 提供了 **AgentCore Gateway**，并配备了受管理的 **Web Search** 工具，以及一个CLI和一个MCP服务器，它们都使用您的 **本地AWS凭证（SigV4/IAM）** 调用Web Search工具，无需API密钥或承载令牌。在单个受管理的搜索工具之上，Scour添加了**并发扩展**和**全文研究**（搜索主题→获取文章→分析引用的语料库），就像一个开源的Firecrawl，可以在您自己的AWS上运行。
底层Web Search完全受管理，符合MCP标准，完全在AWS内提供（零数据外流），价格约为每1000次查询7美元。因为网关使用MCP身份验证调用者与IAM，因此Scour非常适合于基于IAM身份验证的Bedrock托管Agent（例如**Claude Code**，**Codex**或**Cowork**）提供实时网络结果。
> **区域：** Web Search仅在`us-east-1`区域可用。
> [!WARNING]
> **非生产环境。** 这是一个用于学习/实验的示例。它省略了生产环境问题（最小权限范围、监控、速率限制、HA、凭证轮换）。在任何实际使用之前，请审查和调整。
<p align="center">
<img src="assets/demo.gif" alt="Scour demo — 单个搜索，并发批量（URL去重）和针对AgentCore Web Search的全文研究" width="100%">
</p>
## 工作原理
<p align="center">
<img src="assets/architecture.png" alt="Scour架构：客户端→Scour（CLI/MCP/REST）→AgentCore Web Search" width="100%">
</p>
```
您的AWS账户（us-east-1）
任意MCP客户端 ──SigV4 / MCP over HTTPS──▶ AgentCore Gateway ──▶ 网络搜索连接器
（CLI，代理，…） （AWS_IAM身份验证） 假设IAM角色 （托管网络索引）
```
- **入站**（客户端→网关）：每个MCP请求都经过SigV4签名；调用者的IAM主体需要`bedrock-agentcore:InvokeGateway`权限。
- **出站**（网关→连接器）：网关假设一个服务角色，授予`bedrock-agentcore:InvokeWebSearch`权限，完全在AWS内。
网关是一个普通的MCP服务器，因此**任何MCP客户端都可以调用它**。此存储库还附带了一个小型CLI和一个Claude Code技能，参见[使用它](#使用它)了解选项。
## 先决条件
- AWS凭证（`aws configure` / `AWS_PROFILE`）能够创建IAM角色和AgentCore网关，访问`us-east-1`中的Bedrock AgentCore。
- **AWS CLI v2 ≥ 2.35.0**（较旧版本缺少网关`connector`目标形状）。
- **Python 3.9+**（仅限CLI）和/或[`uv`](https://docs.astral.sh/uv/)（仅限直接MCP选项）。
## 安装 — 部署网关（CloudFormation）
此一次性步骤对于以下每个使用选项都是必需的。
[`cfn/agentcore-websearch.yaml`](cfn/agentcore-websearch.yaml)定义了IAM服务角色、网关（`AWS_IAM`入站身份验证）和网络搜索目标。
```bash
aws cloudformation deploy \
--region us-east-1 --stack-name agentcore-websearch \
--template-file cfn/agentcore-websearch.yaml --capabilities CAPABILITY_IAM
# 捕获网关URL（用于以下每个选项）
GATEWAY_URL=$(aws cloudformation describe-stacks --region us-east-1 \
--stack-name agentcore-websearch \
--query "Stacks[0].Outputs[?OutputKey=='GatewayUrl'].OutputValue" --output text)
echo "$GATEWAY_URL"
```
## 使用它
选择适合的选项 — 所有选项都使用相同的网关和相同的IAM/SigV4身份验证：
| 选项 | 最适合… |
|---|---|
| **A. CLI** | 从shell、脚本或cron作业中搜索；需要格式化或`--json`输出 |
| **B. 任意MCP客户端** | 将工具连接到MCP感知应用，无需安装此软件包 |
| **C. Claude Code/Codex** | 让编码代理为您搜索 |
| **D. 并发MCP服务器** | 为*任何*代理提供一个MCP端点，可以并行扩展**多个搜索**（此存储库的`scour-mcp`） |
| **E. 主机REST服务** | 一个普通的HTTP`/search`端点，API密钥保护，任何应用程序/“自定义搜索”插件都可以使用它，而无需AWS凭证（此存储库的`scour-http`） |
### 选项A — CLI
CLI在原始MCP之上增加了人体工程学：参数验证，`.env`加载，整洁的结果格式化，以及一个打包的`scour`命令。
```bash
# 将网关URL保存到CLI查找的位置
printf 'AGENTCORE_GATEWAY_URL=%s\n' "$GATEWAY_URL" > .env
uv venv && . .venv/bin/activate # 通过uv隔离环境（避免依赖冲突）
uv pip install . # 安装`scour`命令
scour "最新AWS新闻" # 基本搜索（默认10个结果）
scour "最新Python版本" -n 5 # -n / --max-results（1-25）
scour "aws re:Invent 2026日期" --json # 原始工具结果JSON（管道到jq）
scour --list-tools # 列出网关工具并退出
scour --help # 完整用法
# 覆盖配置而无需.env /导出变量：
scour "ecs vs eks" \
--gateway-url "$GATEWAY_URL" \
--profile my-aws-profile \
--region us-east-1
```
CLI读取`.env`或环境中的`AGENTCORE_GATEWAY_URL`（和可选的`AWS_PROFILE`）。它的唯一依赖是
[`mcp-proxy-for-aws`](https://pypi.org/project/mcp-proxy-for-aws/)，它处理SigV4签名和MCP传输。
### 选项B — 任意MCP客户端（无CLI）
网关是一个标准的**可流式HTTP MCP**端点。身份验证是**AWS SigV4（IAM）**，在`bedrock-agentcore`服务上，大多数MCP客户端无法自行签名 -
运行AWS的[`mcp-proxy-for-aws`](https://pypi.org/project/mcp-proxy-for-aws/)作为本地stdio MCP服务器，用您的AWS凭证签名请求并转发到网关。无需安装此软件包。
配置为MCP服务器（通用表单；字段名称因客户端而异）：
```jsonc
{
"mcpServers": {
"scour": {
"command": "uvx",
"args": [
"mcp-proxy-for-aws",
"https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp",
"--region", "us-east-1"
],
"env": { "AWS_PROFILE": "your-profile" } // 省略使用默认凭证链
}
}
}
```
它公开一个工具，`WebSearch`（命名为`web-search-tool___WebSearch`），参数`query`（≤200个字符）和可选`maxResults`（1-25）。通过运行代理独立运行：
```bash
uvx mcp-proxy-for-aws "$GATEWAY_URL" --region us-east-1
```
### 选项C — Claude Code或Codex
两个代理支持**两种**添加工具的方法：安装此存储库的**技能**（带有[`SKILL.md`](skills/scour/SKILL.md）的文件夹驱动CLI从选项A），或将网关注册为**MCP服务器**（选项B的代理）。使用哪一个 - 技能需要安装CLI；MCP服务器不需要。
> MCP命令以下列出网关URL。将其替换为`$GATEWAY_URL`，如果您的客户端不扩展环境变量。
**[Claude Code](https://docs.claude.com/claude-code)**
```bash
# 作为技能（需要选项A的CLI）:
cp -r skills/scour ~/.claude/skills/
# …或作为MCP服务器（不需要CLI）：
claude mcp add scour -- uvx mcp-proxy-for-aws "$GATEWAY_URL" --region us-east-1
```
然后询问Claude Code以“搜索网络与agentcore”。
**[Codex](https://developers.openai.com/codex/)**
```bash
# 作为技能（需要选项A的CLI）:
cp -r skills/scour ~/.codex/skills/
```
```toml
# …或作为MCP服务器在~/.codex/config.toml（不需要CLI）：
[mcp_servers.scour]
command = "uvx"
args = ["mcp-proxy-for-aws", "https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp", "--region", "us-east-1"]
```
### 选项D — 并发MCP服务器
此存储库还附带一个MCP **服务器**，`scour-mcp`，它包装网关并添加**并发**搜索 **以及全文研究** - 开源Firecrawl风格的流程：选择主题→搜索→获取文章→获取一个结构化语料库，您的代理可以总结。指向任何MCP客户端并启用后，每个代理都可以访问它。
为什么使用它而不是选项B的原始代理：
- **并发扩展。** `web_search_batch`同时发出多个查询，对AgentCore进行速率限制和限定后合并和**重复URL**。一个问题→多个搜索→一个结果集。
- **全文研究。`fetch_articles` / `research`同时获取结果页面的**完整**文本（Web Search本身仅返回摘要）并提取主要文章文本 - 礼貌地（robots.txt感知，速率限制，限定）。
- **集中身份（可选）。** 在流式HTTP上运行，它保留AWS身份并对上游进行SigV4签名，因此下游代理不需要自己的AWS凭证。运行stdio以使用您自己的凭证。
它公开四个工具：
| 工具 | 参数 | 返回 |
|---|---|---|
| `web_search` | `query`（≤200个字符），`max_results`（1-25，默认10） | `{results:[{title,url,publishedDate,text], total}` |
| `web_search_batch` | `queries[]`，`max_results`，`concurrency?` | 合并，重复URL `{results, total, queryCount, errorCount, queries[]}` |
| `fetch_articles` | `urls[]`，`max_chars?`，`concurrency?` | `{results:[{url,finalUrl,status,title,text,chars,error], total, errorCount}` |
| `research` | `topic`，`max_results`，`fetch_full?`，`max_chars?`，`concurrency?` | `{topic,|sources:[{url,title,publishedDate,snippet,text,fetchError}]}` |
> **工作地点。** `web_search` / `web_search_batch` 完全在AWS内运行（仅限摘要）。`fetch_articles` / `research` 额外从**源服务器获取完整页面** - 该部分不在AWS内。代理/LLM在返回的`sources`上执行最终摘要/分析。
安装并运行（需要网关来自设置，并且设置`AGENTCORE_GATEWAY_URL`）：
```bash
uv pip install . # 安装`scour-mcp`
scour-mcp # stdio（默认）- 本地代理
scour-mcp --http # 流式HTTP在127.0.0.1:8000/mcp
scour-mcp --http --host 0.0.0.0 --port 9000 # 主机供多个代理使用
# 吞吐量旋钮（默认大小调整为AgentCore配额；通过Service Quotas提高）
scour-mcp --rate 10 --concurrency 10
# 全文获取旋钮（礼貌对待源站点）：
scour-mcp --fetch-concurrency 10 --fetch-rate 5 --max-chars 8000
# （robots.txt默认尊重；--no-robots禁用 - 请负责任地使用）
```
对于更高质量的主要文本提取，安装可选的额外功能（提取器自动使用它，在没有时回落到bs4/lxml）：
```bash
uv pip install ".[quality]" # 添加trafilatura
```
将stdio服务器注册到编码代理（它使用您的AWS凭证签名）：
```bash
# Claude Code
claude mcp add scour-concurrent -- scour-mcp
```
```toml
# Codex - ~/.codex/config.toml
[mcp_servers.scour_concurrent]
command = "scour-mcp"
env = { AGENTCORE_GATEWAY_URL = "https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp", AWS_PROFILE = "your-profile" }
```
然后询问代理进行“网络搜索”（一个查询）或“并行搜索这些主题”（批量）。结果包含`url`/`title`/`publishedDate` - **始终引用**。
#### 吞吐量，配额和限制（阅读后再扩展）
批量工具受**AgentCore服务配额**限制（所有在`us-east-1`，所有可通过Service Quotas增加）：
| 配额 | 默认值 | 服务器的保护措施 |
|---|---|---|
| Web Search Tool请求速率 | **10/秒** | `--rate`（令牌桶限制器，默认10） |
| 网关并发连接 | **1000** | `--concurrency`（信号量，默认10） |
| 每查询`maxResults` | **1-25** | 每查询验证 |
| `query`长度 | **≤ 200个字符** | 每查询验证 |
因此，1000次查询批次**可能**，但在默认10 TPS的情况下需要~100s - 通过**Web Search Tool请求速率**配额（和`--rate`）提高fan-out。
> [!IMPORTANT]
> **AgentCore可接受的使用**。Web Search返回*语义提取的摘要*，而不是完整的页面，您必须在任何输出中**保留源引用**（url/title）。您不得将其用于提取/存储/复制结果**批量**或构建竞争性索引。使用并发功能可以更快地**回答问题**，而不是扩大规模以获取内容。
> [!WARNING]
> **完整文本获取（`fetch_articles` / `research`）。** 从其原始站点获取公共URL是普通的Web访问 - 受该站点的robots.txt，条款和版权（非AgentCore的策略）约束。获取器默认尊重robots.txt，速率限制，并限定每个下载。仅获取您有权阅读的页面，保持引用，不要批量重新分发完整文本。
### 选项E — 主机REST搜索服务（`scour-http`）
对于聊天客户端/应用程序希望一个简单的**HTTP URL**（不是MCP），并且对于一个**中央服务，任何工具都可以使用它，并附带API密钥** - 无需下游AWS凭证。`scour-http`是一个微小的REST桥接器：`GET/POST /search` → AgentCore → JSON。它集中保存AWS身份；客户端只提供API密钥。
- **API密钥身份验证**通过`Authorization: Bearer <key>`或`X-API-Key: <key>`。密钥来自`--api-key`（可重复）或`SCOUR_API_KEYS`（逗号分隔环境变量）。
- **默认安全**：拒绝绑定非回环主机而没有密钥（除非`--insecure`）。使用`scour-http --gen-key`生成一个强密钥。
```bash
uv pip install . # uv推荐（避免环境冲突）
KEY=$(scour-http --gen-key)
scour-http --port 3000 --api-key "$KEY" # 本地服务
curl "http://127.0.0.1:3000/search?q=hello&maxResults=5" -H "Authorization: Bearer $KEY"
curl -X POST http://127.0.0.1:3000/search -H "Content-Type: application/json" \
-H "Authorization: Bearer $KEY" \
-d '{"query":"hello","maxResults":5,"exclude":["example.com"]}'
```
- **请求**：`q`或`query`（查询字符串或JSON），可选`maxResults`（1-25，限制为25 - AgentCore的每个查询限制）和`exclude`（要删除的域）。
- **响应**： `{query, total, results:[{title,url,content,snippet,text,publishedDate}]}`。
- 将客户端的**自定义搜索URL**指向`https://<your-host>/search`，并将其结果上限设置为**25**。（如果模型的内置搜索开启，则自定义插件将被绕过。）
#### 将其作为服务托管（systemd + nginx + Cloudflare） - 在任何机器上复制
这是参考部署`https://scour.aws.xin`的运行方式。在任何具有nginx和公共域名的Linux主机上复制：
**1. 最小权限IAM用户**（在网关的账户中 - 只能调用此网关）：
```bash
aws iam create-user --user-name scour-websearch-invoker
aws iam put-user-policy --user-name scour-websearch-invoker --policy-name InvokeOneGateway \
--policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow", "Action":"bedrock-agentcore:InvokeGateway", "Resource":"arn:aws:bedrock-agentcore:us-east-1:<ACCOUNT_ID>:gateway/<GATEWAY_ID>"}]}'
aws iam create-access-key --user-name scour-websearch-invoker # 捕获密钥
```
**2. 在框上安装（uv）+机密文件**（`/etc/scour.env`，权限600 - 永远不要在git上）：
```bash
git clone <your-repo> /opt/scour && cd /opt/scour
uv venv && uv pip install .
sudo install -m 600 /dev/stdin /etc/scour.env <<EOF
AGENTCORE_GATEWAY_URL=https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=<from step 1>
AWS_SECRET_ACCESS_KEY=<from step 1>
SCOUR_API_KEYS=$(/opt/scour/.venv/bin/scour-http --gen-key)
EOF
```
**3. systemd服务**（环回绑定，自动重启，自动启动）：
```ini
# /etc/systemd/system/scour-http.service
[Unit]
Description=Scour HTTP search bridge (AgentCore Web Search)
After=network-online.target
Wants=network-online.target
[Service]
EnvironmentFile=/etc/scour.env
ExecStart=/opt/scour/.venv/bin/scour-http --host 127.0.0.1 --port 8770
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
```
```bash
sudo systemctl daemon-reload && sudo systemctl enable --now scour-http
```
**4. nginx反向代理** - 添加一个*新的*站点文件（不要编辑现有的文件），然后
`sudo nginx -t && sudo nginx -s reload`：
```nginx
server {
listen 443 ssl http2;
server_name scour.<your-domain>;
ssl_certificate /etc/nginx/<your-domain>.pem;
ssl_certificate_key /etc/nginx/<your-domain>.pem;
location / {
proxy_pass http://127.0.0.1:8770;
proxy_set_header Host $host;
proxy_set_header Authorization $http_authorization; # 将API密钥传递给客户端
proxy_set_header Connection "";
proxy_buffering off;
}
}
```
**5. DNS**：将`scour.<your-domain>`指向该框（例如Cloudflare，代理）。
**6. 从任何地方调用它**（只需要API密钥）：
```bash
curl "https://scour.<your-domain>/search?q=...&maxResults=10" \
-H "Authorization: Bearer <SCOUR_API_KEY>"
```
**操作它**：
- 轮换/添加API密钥→编辑`/etc/scour.env`中的`SCOUR_API_KEYS` → `systemctl restart scour-http`。
- 轮换AWS凭证→重新创建IAM访问密钥→更新`/etc/scour.env` →重启。
- 日志→ `journalctl -u scour-http -f`.
> **安全性：** AWS访问密钥仅存在于`/etc/scour.env`（权限600）并且从不发送给客户端 - 它们通过Scour API密钥进行身份验证。IAM用户只能在单个网关上调用`InvokeGateway`，因此泄露的API密钥最多可以运行搜索（在您的账单上），而不能执行其他操作。吞吐量受AgentCore的Web Search配额限制（默认10 TPS；桥接器为每个请求提供一个查询，不会对多个并发请求进行速率限制，因此请使用`web_search_batch`进行大规模扩展）。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器