doc-breach-mcp

<div align="center"> <h1>💥 文档突破 ^(MCP)</h1> <p><b>网络对 AI 代理充满敌意，我们带来了撬棍。</b></p> <br /> <p> <a href="#"><img src="https://img.shields.io/badge/SaaS_Dependencies-Zero-red?style=for-the-badge" /></a> <a href="#"><img src="https://img.shields.io/badge/WAF_Bypass-Automated-success?style=for-the-badge" /></a> <a href="#"><img src="https://img.shields.io/badge/Cost-$0.00_Forever-blue?style=for-the-badge" /></a> <a href="#"><img src="https://img.shields.io/badge/Transport-STDIO-black?style=for-the-badge" /></a> </p> <p> <a href="#-quickstart">快速开始</a> · <a href="#%EF%B8%8F-the-weapon-guerrilla-architecture">架构</a> · <a href="#-the-uncomfortable-truth">为什么存在</a> </p> <img width="1219" height="677" alt="image" src="https://github.com/user-attachments/assets/6e15e72d-d2ce-4b68-b031-b7b5305ab916" /> </div> > **生产环境中使用文档突破？** 我们想听听您的故事 — [**加入 Discord →**](https://discord.gg/pKEdyxAYD) > WAF 恐怖故事、边缘案例以及您正在构建的内容。创始人也在其中。 --- ## 🛑 问题：代理工作流是盲目的 我们处于自主 AI 代理时代，但网络的构建是为了抵御机器人，而不是为它们服务。 当您的 Claude、Cursor 或 Windsurf 尝试读取一个晦涩难懂的 API 文档时，它会被以下内容摧毁： 1. **Cloudflare WAF** 抛出 403 CAPTCHAs 到 Node.js `fetch()`。 2. **空 SPA 外壳** （Next.js、Mintlify、GitBook）如果没有渲染 $300M 的无头浏览器，则不会渲染任何内容。 3. **遗留企业 PDF** 导致模型上下文窗口崩溃。 4. **登录墙** 将公共 API 参考资料锁定在 OAuth 门后。 5. **“AI 友好”SaaS 工具** （Firecrawl、Jina、Context7）为您收取 **$50/mo** 以读取已经公开的页面。 LLM 不需要中间人。它需要 **原始信号**。 --- ## ⚔️ 武器：游击队架构 **文档突破** 是一个无情的、100% 本地的 MCP 服务器。它不需要许可。它使用军事级别的启发式算法从 **任何** 开发人员门户中提取干净的、LLM 优化的 Markdown - 而且它是免费的，永久免费。 | 敌人防御 | 文档突破战术覆盖 | | :--- | :--- | | 🛡️ **Cloudflare / WAF 403** | **时间代理** - 遇到 WAF？悄悄转向 Wayback 机器。去年的文档仍然可用。 | | ⚛️ **JavaScript SPA 墙** | **水化劫持** - 直接从 DOM 中提取 `__NEXT_DATA__`、`__NUXT__`、`__GITBOOK_STATE__`。不需要 JavaScript 引擎。 | | 🪟 **隐藏的 iFrame** | **源代码追踪** - 检测嵌入的 Swagger/Postman/Stoplight 应用程序，销毁包装器，并解析真正的源 URL。 | | 📄 **遗留 PDF 手册** | **本地蛮力** - 内存中 PDF 解析。您的 AI 读取 2004 年的银行手册，就像它们是 GitHub README 一样。 | | 🔐 **登录墙** | **墙检测** - 立即识别 OAuth/SSO 门并告诉代理转向公共替代方案。 | | 🕳️ **鬼城网站** | **自我修复错误** - 未找到文档？文档突破引导代理搜索 GitHub 仓库、SDK 源代码或 `llms.txt` 文件。 | | 💸 **SaaS 抓取税** | **零。永久。** 所有内容都在本地运行，通过 Cheerio 和 Turndown。不需要 API 密钥。不需要帐户。不需要遥测。 | > *"LLM 不应该擅长抓取。它应该擅长编码。文档突破处理脏活。* --- ## 🚀 快速开始 ### Claude 桌面版 添加到 `claude_desktop_config.json`： ```json { "mcpServers": { "docbreach": { "command": "npx", "args": ["-y", "doc-breach-mcp"] } } } ``` ### Cursor / Windsurf 添加到您的 MCP 设置： ```json { "doc-breach": { "command": "npx", "args": ["-y", "doc-breach-mcp"] } } ``` 就是这样。不需要 API 密钥。不需要 `.env` 文件。不需要注册。**它直接运行。** --- ## 🧠 它如何思考 文档突破为您的 AI 代理提供 **4 个精确工具**，并让模型驱动： ``` 您： “与 Datadog API 集成并列出所有监视器” 代理 → docs.discover({ query: "datadog API" }) ← 找到：docs.datadoghq.com/api/latest/ (openapi) 代理 → docs.map({ domain: "docs.datadoghq.com" }) ← 🗺️ 站点地图层次结构，自动生成的 Mermaid 图和 llms.txt 发现 代理 → docs.read({ url: "https://docs.datadoghq.com/api/latest/" }) ← 📄 清洁的 Markdown + 导航链接 + 身份验证要求 代理 → docs.extract({ url: "https://api.datadoghq.com/api/v2/openapi.yaml", tag: "monitors" }) ← 📋 GET /api/v1/monitor — 列出所有监视器 GET /api/v1/monitor/{id} — 获取监视器的详细信息 POST /api/v1/monitor — 创建监视器 ... 代理： “我看到 API 需要 DD-API-KEY 和 DD-APPLICATION-KEY 头， 并且您需要选择一个 DD_SITE（US1、EU、US3、US5、AP1）…” ``` 模型 **推理**。文档突破 **检索**。没有人产生幻觉。 ### 11 步阅读管道 每个 URL 都经过一个经过实战检验的 11 步提取管道： ``` URL │ ├─ 1. 预飞行 ──────── HEAD 检查 → Content-Type，大小，拒绝 >10MB ├─ 2. 获取 ──────────── GET + Wayback 机器在 403/503 时作为备用 ├─ 3. 登录检测 ── OAuth/SSO 墙？ → 终止 + 引导代理 ├─ 4. 格式检测 ─ OpenAPI？Postman？PDF？llms.txt？Markdown？ ├─ 5. 二进制处理 ── PDF <5MB → 内存解析 ├─ 6. 规范摘要 ───── OpenAPI/Postman → 结构化 Markdown ├─ 7. SPA 水化 ──── __NEXT_DATA__，__NUXT__，readme-data，GitBook ├─ 8. 导航提取 ─── 侧边栏链接 → 绝对 URL ├─ 9. iFrame 情报 ───── Swagger/Postman/Stoplight 嵌入 → 真实 URL ├─ 10. HTML 清理 ─── Cheerio → 删除头部、页脚、广告、导航 └─ 11. Markdown ──────── Turndown + 边界感知截断 │ ▼ 清洁的、LLM 准备好的 Markdown ``` --- ## 🪖 不舒适的真相 开发者工具市场有一个寄生虫问题。 像 Firecrawl、Jina Reader 和 Context7 这样的公司拿 **公共文档** —— 任何浏览器都可以自由访问的页面 —— 并用专有 API 包装它们，然后向您收取每月订阅费来访问实际上已经属于您的内容。 它们没有增加价值。它们添加了一个 **收费站** 到公共互联网上。 文档突破存在是因为： - **文档是公开的。** 如果人类可以阅读它，代理也应该可以。 - **抓取是一个已经解决的问题。** Cheerio + Turndown 已经存在十年了。您不需要一个价值 2000 万美元的初创公司来解析 HTML。 - **您的 AI 在本地运行。** 为什么它应该向 SaaS 电话回家读取 README？ 这不是产品。这是 **撬棍**。 --- ## 📊 文档突破 vs. 收费站 | | 文档突破 | Firecrawl | Jina Reader | Context7 | |---|:---:|:---:|:---:|:---:| | **成本** | $0 | $50+/月 | $30+/月 | 免费（有限） | | **本地运行** | ✅ | ❌ 云 | ❌ 云 | ❌ 云 | | **不需要 API 密钥** | ✅ | ❌ | ❌ | ❌ | | **不需要遥测** | ✅ | ❌ | ❌ | ❌ | | **WAF 绕过** | ✅ Wayback | ✅ 付费代理 | ❌ | ❌ | | **SPA 提取** | ✅ 水化 | ✅ 无头 | ❌ | ❌ | | **PDF 解析** | ✅ 原生 | ✅ | ❌ | ❌ | | **OpenAPI 提取** | ✅ | ❌ | ❌ | ❌ | | **HATEOAS 导航** | ✅ | ❌ | ❌ | ❌ | | **认知规则** | ✅ | ❌ | ❌ | ❌ | | **开源** | ✅ MIT | 部分 | ❌ | ✅ | --- ## 🔧 工具参考 ### `docs.discover` > 为任何服务、库或 API 查找文档源。 ```typescript docs.discover({ query: "stripe webhooks API" }) // → [ { url, title, type: "openapi", source: "probe" }, ... ] ``` ### `docs.map` > 映射任何域名的完整文档结构。提取站点地图、robots.txt 和 llms.txt，返回架构蓝图。 ```typescript docs.map({ domain: "docs.stripe.com" }) // → { total: 1200, sections: { "Root": [...], "API": [...] }, ... } ``` ### `docs.read` > 读取任何文档 URL 并返回干净的、LLM 准备好的 Markdown。 ```typescript docs.read({ url: "https://docs.stripe.com/webhooks" }) // → { content: "# Webhooks\n\n...", nav_links: [...], format: "html" } ``` ### `docs.search` > 在文档站点中搜索特定主题。 ```typescript docs.search({ query: "authentication", site: "docs.stripe.com" }) // → [ { url: ".../authentication", title: "身份验证", ... } ] ``` ### `docs.extract` > 从 OpenAPI/Swagger/Postman 规范中提取结构化的端点信息。 ```typescript docs.extract({ url: "https://api.stripe.com/openapi/spec.json", tag: "charges" }) // → [ { method: "POST", path: "/v1/charges", summary: "创建收费" }, ... ] ``` --- ## 🏆 超越 MCP 规范 谷歌和 Anthropic 的官方 MCP 最佳实践要求“单一责任”、“清晰的描述”和“结构化的错误处理”。这是最低要求。 借助 [**Vurb.ts**](https://github.com/vinkius-labs/vurb.ts)，文档突破将这些概念提升到十倍，运行在标准协议的前沿： - **MVA 架构（模型 → 视图 → 代理）**：标准 MCP 返回原始 JSON 字符串。我们通过 Fluent Presenters 将所有内容路由到智能出口防火墙，在 LLM 看到它们之前去除噪音。 - **HATEOAS 导航**：代理不必猜测下一步该做什么。每个文档突破响应都包含一个 `.suggestActions()` 有效载荷，告诉模型下一步该调用哪个工具。 - **JIT 系统规则**：根据有效载荷上下文动态注入指令（例如，“内容被截断，请使用搜索”）。 - **自我修复错误**：标准 MCP 抛出错误。文档突破返回错误 **和** 恢复错误的确切提示/工具。 - **服务器端 Mermaid UI**：向 MCP 检查员发送原生 `ui.mermaid()` 视觉图表，以帮助人类查看代理看到的架构。 - **状态同步和缓存控制**：在协议级别发出 `.cached()` 指令，以消除重复请求并节省 LLM 上下文。 --- ## 📄 许可证 MIT — 因为文档应该是免费的，读取文档的工具也应该是免费的。 --- <div align="center"> <br /> <p><b>停止为读取公共网页付费。</b></p> <p>⭐ 如果您同意，请给这个仓库点赞。</p> </div>