内容
<div align="center">
<img src="assets/banner.svg" alt="Argus - 自托管的网络智能 MCP" width="100%" />
<br/>
<a href="https://github.com/jlowin/fastmcp"><img src="https://img.shields.io/badge/MCP-Streamable_HTTP-2dd4bf?style=for-the-badge&logo=anthropic&logoColor=white" alt="MCP"/></a>
<img src="https://img.shields.io/badge/tools-20-22c55e?style=for-the-badge" alt="20 个工具"/>
<img src="https://img.shields.io/badge/tests-600_passing-3fb950?style=for-the-badge&logo=pytest&logoColor=white" alt="测试"/>
<img src="https://img.shields.io/badge/SSRF_coverage-100%25-16a34a?style=for-the-badge&logo=shieldsdotio&logoColor=white" alt="SSRF 100%"/>
<img src="https://img.shields.io/badge/python-3.12-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="python"/>
<br/>
<img src="https://img.shields.io/badge/status-LIVE-22c55e?style=for-the-badge" alt="在线状态"/>
<img src="https://img.shields.io/badge/self--hosted-unlimited-0ea5e9?style=for-the-badge" alt="自托管，无限制"/>
<img src="https://img.shields.io/badge/cost-%240%2Frequest-22c55e?style=for-the-badge" alt="零成本/请求"/>
<img src="https://img.shields.io/badge/truncation-none-14b8a6?style=for-the-badge" alt="无截断"/>
<img src="https://img.shields.io/badge/LLM-not_required-8957e5?style=for-the-badge" alt="无需大型语言模型"/>
<img src="https://img.shields.io/badge/owner-SURIOTA-0d9488?style=for-the-badge" alt="SURIOTA"/>
<br/><br/>
<!-- Dynamic repo-stat badges: render once the repo is PUBLIC (shields.io can't read private repos). -->
<img src="https://img.shields.io/github/last-commit/GifariKemal/argus-web-mcp?style=flat-square&color=22c55e" alt="最后一次提交"/>
<img src="https://img.shields.io/github/languages/top/GifariKemal/argus-web-mcp?style=flat-square&color=2dd4bf" alt="主要语言"/>
<img src="https://img.shields.io/github/languages/count/GifariKemal/argus-web-mcp?style=flat-square&color=14b8a6" alt="语言数量"/>
<img src="https://img.shields.io/github/languages/code-size/GifariKemal/argus-web-mcp?style=flat-square&color=0ea5e9" alt="代码大小"/>
<img src="https://img.shields.io/github/repo-size/GifariKemal/argus-web-mcp?style=flat-square&color=8957e5" alt="仓库大小"/>
<img src="https://img.shields.io/github/commit-activity/m/GifariKemal/argus-web-mcp?style=flat-square&color=d29922" alt="提交活动"/>
<br/><br/>
<img src="https://readme-typing-svg.demolab.com/?font=Fira+Code&weight=600&size=22&pause=900&color=2DD4BF¢er=true&vCenter=true&width=820&lines=全视化的网络层，用于Claude+Code+%26+Codex;取代Jina+%2F+Brave+%2F+Firecrawl+%2F+Exa+-+自托管;搜索+%2F+抓取+%2F+读取+%2F+研究+%2F+无限+%2F+自有;工具，非大脑-您的代理执行思考" alt="标语"/>
</div>
---
> **Argus Panoptes** - 全视化的百眼巨人。 一个自托管的 **无限**、**自有** 的网络 **获取 / 抓取 / 搜索** MCP 服务器，适用于 **SURIOTA**。 与 **Hermes AI Server** 是神话中的兄弟姐妹。 每个 Claude Code / Codex CLI 都通过 **远程 HTTP** 连接 -> **客户端零本地进程**。
## 目录
- [为什么选择 Argus](#为什么选择Argus)
- [架构](#架构)
- [20 个工具](#20-个工具)
- [硬性保证](#硬性保证)
- [快速开始（本地）](#快速开始本地)
- [连接 CLI](#连接CLI)
- [基准测试](#基准测试)
- [仓库地图](#仓库地图)
- [状态](#状态)
## 为什么选择 Argus
我们调查了 12 种领先的付费/免费网络工具。 **所有** 工具都有请求限制、截断内容或需要付费。 Argus 建立在最佳的开源软件基础上，**在 SURIOTA VPS 上自行托管** - 因此它是无限的、免费的、按请求计费的、返回 **完整内容（无截断）**，并且 **端到端拥有**。 它是 **工具，而不是大脑**：消费代理（Claude Code 的 Opus 4.8 / Codex）执行推理 - Argus **不需要大型语言模型**。
| 您正在为... 付费 | Argus 取代它 | 优势 |
|---|---|---|
| Brave / Tavily / Exa **搜索** | `search` / `smart_search` (SearXNG, 70+ 引擎) | 无限，多引擎 + **语义重新排序** |
| Jina Reader / Firecrawl **抓取** | `read` / `scrape` / `batch_read` / `crawl` | 完整内容，JS 渲染 + 隐身， **无截断** |
| Jina / Firecrawl **PDF** | `read_pdf` (pymupdf4llm + Docling) | 表格保留（COT/FOMC） |
| Firecrawl **提取** / **映射** | `extract_structured` / `map_urls` | CSS/XPath，站点地图发现 |
| Exa **查找相似** / 答案 | `find_similar` / `research(deep)` | **本地嵌入**，完整内容包 |
| - （无竞争对手自行托管） | `github_search` / `scholar_search` / 交易提取器 / `watch` | 结构化的 GitHub / 学术 / 外汇护城河 |
## 架构
<div align="center">
<img src="assets/architecture.svg" alt="Argus 架构" width="100%" />
</div>
**获取策略（便宜 -> 昂贵）：** httpx 静态 -> trafilatura -> 升级到 Crawl4AI/Playwright 仅当 JS/薄 -> Patchright 隐身于反机器人 -> **Wayback 存档** 如果主机无法访问。 每个跳跃都受到 SSRF 保护。
## 20 个工具
<details open>
<summary><b>搜索与发现</b></summary>
<br/>
| 工具 | 功能 |
|---|---|
| `search` | 通过 SearXNG 进行网络搜索 - 类别（常规/新闻/科学/IT），域名过滤器，安全搜索， **混合词典+语义重新排序**，新鲜度提升，自动退避以应对限流 |
| `smart_search` | 自动路由查询（确定性， **无需大型语言模型**）-> github / scholar / news / it / general |
| `scholar_search` | 结构化学术搜索（Semantic Scholar -> CrossRef）：引用，DOI，摘要，OA-PDF |
| `github_search` | 结构化的 GitHub `repositories`/`code`/`issues` + stars/language/sort |
| `map_urls` | 发现站点的 URL（sitemap.xml / robots.txt / 1-hop 链接） |
| `find_similar` | 通过 **本地嵌入**（Exa-style，无 API）查找语义相关的页面 |
</details>
<details>
<summary><b>获取与读取</b></summary>
<br/>
| 工具 | 功能 |
|---|---|
| `read` | URL -> 清洁的 markdown/text/html， **无截断**；`extract_media` 添加链接+图片 |
| `scrape` | JS-rendered 获取 + 截图/动作；自动升级到 **Patchright 隐身** 以对抗反机器人 |
| `batch_read` | 多个 URL 的并行 `read`，部分失败容忍 |
| `read_pdf` | PDF -> markdown + 表格（pymupdf4llm；`mode='quality'` -> Docling 用于扫描/复杂） |
| `crawl` | Crawl4AI BFS 深度抓取，尊重 robots，域名限定 |
| `screenshot` | 页面的完整 PNG 捕获 |
</details>
<details>
<summary><b>提取与研究</b></summary>
<br/>
| 工具 | 功能 |
|---|---|
| `extract_structured` | 通过 CSS/XPath 选择器提取字段（确定性）；可选的大型语言模型层（`auto`/`llm`） |
| `research` | 一次性：`deep`（搜索 -> 完整读取 top-K -> 捆绑）/ `quick`（点击）/ `answer`（引用，可选大型语言模型）；`highlights`=每个来源的顶级句子；可选 `max_chars_per_source` |
</details>
<details>
<summary><b>监控与交易护城河</b></summary>
<br/>
| 工具 | 功能 |
|---|---|
| `watch` / `list_watches` / `unwatch` | 轮询页面（完整或选择器）-> 通过 webhook（例如 Telegram）发送更改 |
| `forexfactory_calendar` | 经济日历（FairEconomy JSON）-> Aurix `calendar_client` 形状 |
| `cot_report` | CFTC 交易者承诺，结构化 |
| `news_sentiment_feed` | 排名新闻 + 可选的情绪评分 |
> 交易解析器验证为 **>=99% 字段准确率**（100% 在黄金文件中）。
</details>
## 硬性保证
- **SSRF** - 解析后验证，IP-pin 防反绑定，方案允许列表，每个跳转重定向重新检查，私有/元数据/CGNAT 拒绝 -> **100% 测试覆盖率**，行 + 分支（硬门）。
- **无静默截断** - 始终是完整文档；流式传输主体上限是 DoS 防护，而不是内容上限。
- **工具永远不会引发** - 每个工具都返回一个结构化的 `err(code, msg, detail)` 而不是崩溃到客户端。
- **弹性** - 内容寻址缓存（每个源的 TTL，备用服务），每个主机的礼貌延迟 + 电路中断器，存档出口备用。
- **安全部署** - bearer/JWT 身份验证 + nginx TLS + fail2ban；通过 systemd 以非特权方式运行；通过 `EnvironmentFile` 进行秘密管理。
## 快速开始（本地）
```bash
uv venv --python 3.12 && uv pip install -e ".[dev]"
crawl4ai-setup && crawl4ai-doctor # 一次性 Chromium
# 可选附加项：".[semantic]"（find_similar/rerank），".[pdf-quality]"（Docling）
# SearXNG（搜索后端）- 仅限循环
cd deploy/searxng && docker compose up -d
python -m argus.server # stdio（本地开发）
# 或 HTTP： uvicorn argus.server:app --host 127.0.0.1 --port 8090
```
## 连接 CLI
使用 **Claude Code** 注册：
```bash
claude mcp add --transport http argus https://argus.gifariksuryo.xyz/mcp \
--header "Authorization: Bearer ${ARGUS_TOKEN}"
```
使用 **Codex** 注册（`~/.codex/config.toml`）：
```toml
[mcp_servers.argus]
url = "https://argus.gifariksuryo.xyz/mcp"
bearer_token_env_var = "ARGUS_TOKEN"
```
## 基准测试
与 Claude Code & Codex **原生** 网络工具（4 路，n=25，相同查询）进行对比：**发现能力相当**，但 Argus 在 **内容深度**（每个查询的完整内容 vs 点击/摘要），新鲜度和成本/所有权方面获胜。 进程内 `research()` 在 **3-6 秒** 内运行 - Argus 不是延迟瓶颈（CLI 延迟是消费代理 + MCP 传输）。 Claude+Argus 在最深的合成中保持标记中立； Codex+Argus 交易 +72% 标记以获取该深度。 语义重新排序量化为 **+27% nDCG** 在概念查询上。 完整报告： [`benchmark/RESULTS.md`](benchmark/RESULTS.md) ([harness](benchmark/README.md)).
## 仓库地图
| 路径 | 功能 |
|---|---|
| `src/argus/` | 包 - `server.py`（20 个工具），`fetch/`，`extract/`，`security/ssrf.py`，`trading/`，`semantic.py`，`cache.py`，`watch.py` |
| `docs/` | [DESIGN](docs/00-DESIGN.md) / [RESEARCH](docs/01-RESEARCH.md) / [ROADMAP](docs/02-ROADMAP.md) / [TOOL-SPECS](docs/03-TOOL-SPECS.md) / [REFERENCES](docs/04-REFERENCES.md) / [COMPETITIVE-GAP](docs/05-COMPETITIVE-GAP.md) |
| `benchmark/` | [harness](benchmark/README.md) + [RESULTS](benchmark/RESULTS.md) + 对比 |
| `deploy/` | systemd / nginx / provision.sh / fail2ban / [SECURITY-AUDIT](deploy/SECURITY-AUDIT.md) / [runbook](deploy/README.md) / searxng/ |
| 根目录文档 | [SOUL](SOUL.md)（身份）/ [AGENTS](AGENTS.md)（代理指南）/ [CHANGELOG](CHANGELOG.md)（历史） |
## 状态
**已部署上线。** 公共 HTTPS 在 **https://argus.gifariksuryo.xyz/mcp** （带有身份验证令牌）位于 SURIOTA VPS (`103.172.172.29`，Ubuntu 24.04）：uvicorn `127.0.0.1:8090 --workers 1` 在 nginx + Let's Encrypt TLS + fail2ban 后面； SearXNG docker 在 `127.0.0.1:8888`； `/health` + `/metrics` 已上线。 systemd 计时器每 5 分钟轮询 `main` -> 仅快进 -> 重启 -> `/health` 门控 -> 自动回滚（并跳过文档/基准测试提交）。
20 个工具 / **600 个离线测试**（+ 浏览器和慢速额外功能）绿色 / **SSRF 100%**（行 + 分支）/ ruff clean / 安全审计（无关键/高）。 可选且默认关闭：大型语言模型层（`ARGUS_ENABLE_LLM`）和本地路径 PDF（`ARGUS_ALLOW_LOCAL_PDF`）。 仅开放所有者输入：设置 `ARGUS_S2_API_KEY` 以启用 `scholar_search` 的 Semantic Scholar 后端（CrossRef 是备用）。 参见 [`docs/02-ROADMAP.md`](docs/02-ROADMAP.md)。
<div align="center">
<sub>为 <b>PT Surya Inovasi Prioritas (SURIOTA)</b> / 自托管 / 无限制 / 自有而构建</sub>
</div>
