内容
# VOZ 知识 MCP
用于归档、搜索和总结 [VOZ](https://voz.vn/) 论坛帖子的本地 MCP 服务器。它存储帖子内容本地，清理论坛噪音，保留有用链接，并为 AI 代理构建整帖数据包，以合成实用的知识笔记。
目标论坛： [https://voz.vn/](https://voz.vn/)
## 功能
- 爬取公开的 VOZ 帖子并将帖子/资产保存到 SQLite。
- 当公开内容不完整时，使用已登录的 Chromium 家族浏览器作为备用。
- 快速搜索归档帖子，或按主题分组搜索结果。
- 构建整帖数据包，用于长篇见解写作，而不是依赖小搜索样本。
- 提取有用链接，同时移除 VOZ 机制，如 `goto/post?id=...`。
- 在本地忽略文件夹中保留人类可读的报告和机器可读的爬取数据。
## 快速开始
需要 Python 3.10+。
```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
```
运行快速公开爬取：
```bash
python -m voz_knowledge_mcp.cli summarize-thread "https://voz.vn/t/example.123/" --mode public
```
人类可读的 VOZ Markdown 输出写入 `reports/voz/` 下。爬取数据、原始 HTML、JSON 导出和数据包写入 `archive/` 下。
以 MCP 服务器运行：
```bash
python -m voz_knowledge_mcp.server
```
## MCP 客户端配置
示例 MCP 配置：
```toml
[mcp_servers.voz_knowledge]
command = "/path/to/voz-knowledge-mcp/.venv/bin/python"
args = ["-m", "voz_knowledge_mcp.server"]
cwd = "/path/to/voz-knowledge-mcp"
```
尽可能使用虚拟环境中的 Python 可执行文件。如果您的 MCP 客户端通过 shell 启动命令，则相同的命令是：
```bash
cd /path/to/voz-knowledge-mcp
.venv/bin/python -m voz_knowledge_mcp.server
```
代理配套代码：`skills/voz-knowledge/SKILL.md`。
## 工具
| 工具 | 使用场景 |
| --- | --- |
| `read_thread(url, mode="auto", max_pages=None)` | 归档 VOZ 帖子并返回结构化帖子/资产。 |
| `summarize_thread(url, mode="auto")` | 在 `reports/voz/summaries/` 下创建可读的 Markdown 摘要。 |
| `search_archive(query, limit=50)` | 在归档帖子中快速查找关键词。 |
| `search_archive_grouped(query, limit_per_group=5, max_matches=500)` | 搜索并按主题分组匹配帖子。 |
| `extract_links(url, mode="auto")` | 从帖子中提取外部链接、图片和附件。 |
| `crawl_threads(urls, mode="auto", max_pages=None)` | 归档多个帖子。 |
| `build_thread_packet(url, mode="auto", max_posts=None)` | 构建干净的整帖数据包用于见解合成。 |
| `topic_digest(url, topic, mode="auto", max_posts=200)` | 从整帖中提取一个主题。 |
| `setup_browser_cdp()` | 准备本地浏览器备用端点。 |
## CLI 示例
```bash
python -m voz_knowledge_mcp.cli read-thread "https://voz.vn/t/example.123/" --mode public --max-pages 2
python -m voz_knowledge_mcp.cli summarize-thread "https://voz.vn/t/example.123/" --mode auto
python -m voz_knowledge_mcp.cli search-archive "keyword"
python -m voz_knowledge_mcp.cli search-archive-grouped "affiliate"
python -m voz_knowledge_mcp.cli build-thread-packet "https://voz.vn/t/example.123/"
python -m voz_knowledge_mcp.cli topic-digest "https://voz.vn/t/example.123/" "facebook reels"
```
## 知识工作流
`search_archive` 仅用于快速查找。不要使用小搜索结果集作为整帖见解写作的基础。
对于知识合成：
1. 使用 `read_thread` 或 `summarize_thread` 归档帖子。
2. 使用 `build_thread_packet` 构建整帖数据包，或使用 `topic_digest` 提取一个主题。
3. 删除低信号帖子，如 bump、bookmark、仅感谢的回复、应用签名和空回复。
4. 保留有意义的资源：VOZ 附件、VOZ 帖子/链接、YouTube、Reddit、Facebook、TikTok、X/Twitter、Telegram、工具页面、文件和其他外部引用。
5. 删除论坛机制，如 `voz.vn/goto/post?id=...`、个人资料/分享/引用链接、表情符号 CDN 和 `data:image` 占位符。
6. 在编写指南之前检查保留的内容链接。
7. 将截图视为与其源帖子绑定的证据，而不是独立的声明。
配套技能包括 `references/insight-writing.md`，用于将长 VOZ 帖子转换为有用的知识笔记。
## 读取模式
`mode="auto"` 首先读取公共内容，然后尝试浏览器模式。如果浏览器返回可读帖子，MCP 使用浏览器结果并停止。如果浏览器备用失败，它在公共内容可用时保留公共基线。
`mode="public"` 仅读取无需登录即可查看的内容。
`mode="browser"` 通过配置或自动启动的 Chromium 家族浏览器端点读取。
## 浏览器备用和 CDP
浏览器模式使用 CDP，即 Chrome DevTools Protocol。CDP 是 Chromium 家族浏览器（如 Brave、Chrome、Edge、Chromium、Arc、Vivaldi、Opera 和 Coc Coc）公开的本地控制端口。
普通浏览器窗口不公开 CDP。浏览器模式首先使用配置的 CDP 端点，然后自动尝试使用已安装的 Chromium 家族浏览器启动本地 CDP 端口。您也可以在爬取前显式运行 `setup_browser_cdp()`。
仅使用 `127.0.0.1` 端点。不要将 CDP 公开到公共网络，因为任何可以访问该端口的人都可以控制该浏览器会话。
自动启动使用 `archive/browser-profiles/` 下的专用本地浏览器配置文件。如果浏览器备用需要身份验证内容，请在启动的配置文件中登录 VOZ 一次。
使用 Brave 的手动覆盖示例：
```bash
/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser --remote-debugging-port=9222
export VOZ_BROWSER_CDP_URL=http://127.0.0.1:9222
python -m voz_knowledge_mcp.cli read-thread "https://voz.vn/t/example.123/" --mode browser
```
可以按顺序尝试多个已登录的浏览器：
```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9223
/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser --remote-debugging-port=9222
export VOZ_BROWSER_CDP_URLS=http://127.0.0.1:9223,http://127.0.0.1:9222
python -m voz_knowledge_mcp.cli read-thread "https://voz.vn/t/example.123/" --mode browser
```
`VOZ_BROWSER_CDP_URLS` 优先。之后，有限的备用顺序是：
```text
VOZ_CHROME_CDP_URL
VOZ_BRAVE_CDP_URL
VOZ_EDGE_CDP_URL
VOZ_CHROMIUM_CDP_URL
VOZ_ARC_CDP_URL
VOZ_VIVALDI_CDP_URL
VOZ_OPERA_CDP_URL
VOZ_COCCOC_CDP_URL
VOZ_BROWSER_CDP_URL
```
设置 `VOZ_AUTO_LAUNCH_BROWSERS=0` 以禁用自动浏览器启动，仅使用配置的 CDP 端点。
## 本地数据
路径相对于项目目录或 MCP `cwd`，而不是固定机器路径。
人类可读的 VOZ 文档写入 `reports/voz/` 下：
- `reports/voz/summaries/`：由 `summarize_thread` 创建的 Markdown 摘要。
- `reports/voz/`：由 MCP 输出创建的最终人类编写的 VOZ 见解笔记或指南的推荐位置。
机器可读的爬取数据写入 `archive/` 下：
- `archive/voz_archive.sqlite`：SQLite 归档。
- `archive/raw/`：用于调试的原始 HTML 快照。
- `archive/exports/`：JSON 导出。
- `archive/packets/`：整帖知识数据包。
- `archive/browser-profiles/`：用于自动启动的浏览器备用的专用浏览器配置文件。
`reports/` 和 `archive/` 都被 git 忽略，因为它们可能包含爬取的论坛内容、私人会话数据或用户特定的笔记。
您可以覆盖默认值：
```bash
python -m voz_knowledge_mcp.cli --reports-dir reports/voz --archive-dir archive summarize-thread "https://voz.vn/t/example.123/"
```
对于 MCP 服务器使用，设置环境变量：
```bash
VOZ_REPORTS_DIR=reports/voz
VOZ_ARCHIVE_DIR=my-archive
VOZ_ARCHIVE_DB=my-archive/voz_archive.sqlite
```
## 限制
- 该项目不绕过 VOZ 权限或登录要求。
- 它不存储 VOZ 密码。
- 它默认不使用 cookie。
- 它在 v1 中不执行 OCR 或解释截图。
- 搜索基于关键词/启发式；v1 中不包含语义嵌入搜索。
- MCP 准备干净的源材料。最终的见解编写仍应由 AI 代理或人类审查员完成。
## 隐私和安全
保持此服务器本地。不要公开暴露浏览器 CDP 端口。不要提交 `archive/`、`reports/`、浏览器配置文件、cookie、导出的私人内容或其他会话数据。
在总结论坛内容时，保留有用的源链接，避免将未经验证的声明作为事实呈现。
## 测试
```bash
python -m unittest discover -s tests -v
```
## 许可证
MIT
