web_to_readable

打破微信之门，让 agent 自由读取公众号文章。

English · 中文

给一个网址，调用一次 MCP，直接拿到完整 Markdown 正文。工具自动加载网页、提取文章、下载图片，并保存 Markdown、JSON 和离线 HTML；需要 PDF 时再开启。正文提取和文件生成全部由脚本完成，无需模型改写、API Key 或第二次文件读取。

适用于公开可访问的微信公众号文章及常规网页。它使用独立浏览器会话，不会绕过登录墙、验证码或访问权限。

功能

• 一次调用直接返回正文：markdown 字段与首个 MCP 文本块均为可读正文，默认不主动截断。

• 微信公众号正文识别：优先使用 #js_content，兼容 article、main 和自定义正文选择器。

• 本地图片与图表：保留原图；GIF/WebP 等提供 PNG 预览，SVG/canvas 图表自动保存为可查看的图片。

• 可携带的文章资料夹：Markdown 按顺序引用本地图片，JSON 保存元数据与完整图片清单。

• 按需导出 PDF：include_pdf: true 同步生成 PDF；PDF 直链也可提取文字层。

• 明确报告失败项：过滤空占位与隐藏图片，实际图片失败、正文回退及返回截断均有标记。

Related MCP server: SmartFetch

安装

需要 Python 3.11+。下载源码并进入项目目录后，在 macOS / Linux 执行：

git clone https://github.com/asg4090/web-to-readable.git
cd web-to-readable
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
python -m playwright install chromium

Windows 可使用 py -m venv .venv，然后运行 .venv\Scripts\Activate.ps1，其余 Python 命令相同。Linux 若缺少浏览器系统库，可执行 python -m playwright install --with-deps chromium。

安装后有两个等价入口：

web-to-readable
python -m web_to_readable

不传网址时运行 MCP stdio 服务。此项目的发布包可从源码安装；本文不假定它已发布到 PyPI。

接入 MCP

服务名和主工具名均为 web_to_readable。在支持 stdio 的 MCP 客户端中添加：

{
  "mcpServers": {
    "web_to_readable": {
      "command": "web-to-readable",
      "args": []
    }
  }
}

若桌面客户端找不到虚拟环境中的命令，将 command 改为该虚拟环境 Python 的绝对路径，并设置 args: ["-m", "web_to_readable"]。macOS/Linux 的解释器位于 .venv/bin/python，Windows 位于 .venv\Scripts\python.exe。请替换为自己的路径，不要在公开仓库中提交个人配置。

建议客户端工具超时至少设为 150 秒；工具内部转换上限为 120 秒。配置模板见 examples/mcp-config.json。mcp.json 与 plugin.json 提供可选插件打包元数据；独立 MCP 安装无需插件目录。

一次调用读取文章

调用 web_to_readable：

{"url":"https://mp.weixin.qq.com/s/ARTICLE_ID"}

同次响应直接包含：

{
  "status": "ok",
  "markdown": "# 文章标题\n\n完整正文……",
  "content_format": "markdown",
  "content_truncated": false,
  "next_offset": null,
  "markdown_path": ".../article.md",
  "json_path": ".../article.json",
  "images": [{"id":"image-001","status":"ok","read_path":".../images/image-001.png"}],
  "pdf_path": null
}

images[].read_path 可用于继续查看图表；图片像素不会作为正文自动塞入响应。主工具已经返回全文时，直接读取 markdown 即可。完整 Python 客户端示例见 examples/client.py，其中只有一次工具调用。

额外生成 PDF：

{"url":"https://mp.weixin.qq.com/s/ARTICLE_ID","include_pdf":true,"paper":"A4"}

参数

客户端本身可能限制非常大的工具输出。显式设置 max_content_chars 时，脚本会返回 content_truncated、returned_chars、total_chars 与 next_offset。需要续读或之后重读时，可调用辅助工具：

{"json_path":"本工具返回的 json_path","offset":12000,"max_chars":12000}

工具名为 read_exported_article。将 next_offset 传入下一次 offset，直到为 null；单次最多读取 24000 字符。它只读取配置输出目录中的文章 JSON，不重新访问网页。

文件与命令行

默认保存至 ~/Downloads/web-to-readable/，每次创建独立资料夹：

文章标题-时间-唯一后缀/
├── article.md
├── article.json
├── article.html
├── article.pdf          # 可选
└── images/
    ├── image-001.webp
    ├── image-001-preview.png
    └── image-002.png

JSON 保存标题、作者、发布时间、来源、完整 Markdown、图片状态与文件清单。无法提取的作者或时间保留为空字符串。分享正文及图片时请携带整个资料夹。

# 自动保存正文与图片，并将完整响应作为 JSON 输出到终端
web-to-readable 'https://mp.weixin.qq.com/s/ARTICLE_ID'

# 同时保存 PDF
web-to-readable 'https://mp.weixin.qq.com/s/ARTICLE_ID' --pdf

# 自定义正文区域
web-to-readable 'https://example.org/article' --content-selector 'article'

标准输出用于 MCP 协议或 CLI JSON，诊断日志输出到标准错误。

配置

兼容旧版 WEB_PDF_OUTPUT_DIR 和 WEB_PDF_ALLOW_FAKE_IP_DNS。代理兼容模式仅放行具名域名映射到 198.18.0.0/15、2001:2::/48 的情况，不允许相应的直接 IP 网址。

边界

• 每次调用使用独立浏览器，没有现成登录态；访问限制会报错或提示。

• 最多滚动 45 个视口，处理本次加载的内容；不自动追踪文章分页。

• 正文区无法识别时回退到可见页面内容，并提示可能混入页面元素。

• 单张图像数据最多 12 MB，最多处理 150 个图像，下载数据预算 100 MB；预览另行保存。

• 原图下载失败时可自动保存已显示图片的截图，并标注；动态图像预览为静态首帧。

• PDF 直链从文字层提取正文，不自动 OCR，也不拆出 PDF 内的图片。

• 这是个人本地 stdio 工具。网络检查不能代替公共托管服务的完整隔离，详见 SECURITY.md。

请仅处理自己有权访问和保存的内容。MIT 许可证适用于本项目代码，网页文章和图片仍由原权利人享有权利。

开发与打包

python -m pip install -e '.[dev]'
python -m playwright install chromium
python -m unittest discover -s tests -v
python -m build
python -m twine check dist/*

测试使用本地合成页面，覆盖动态中文、图片与图表、Markdown 结构、PDF 导出、一次调用返回全文、续读和路径边界，不依赖真实微信文章。GitHub Actions 配置提供 Linux / Python 3.11–3.13 测试矩阵。

贡献说明见 CONTRIBUTING.md，依赖说明见 THIRD_PARTY_NOTICES.md。

许可证

MIT