MCP 服务器

agent-reader

An MCP server that enables AI agents to instantly convert Markdown into beautiful, ready-to-deliver Word, PDF, HTML with sidebars, and Slideshow documents, bridging the "last mile" of AI content generation.

README

English | 中文

Agent Reader — AI Agent 的文档美化引擎

AI Agent 擅长生成内容，但输出的 Markdown 对普通人不友好。Agent Reader 一键把 Markdown 变成漂亮网页、Word、PDF，还能把图片做成全屏幻灯片。

专为 AI Agent 时代打造的格式化引擎 — Agent 调用一次，输出即交付。

核心能力

能力	说明
📄 Markdown → 网页	带侧边目录导航、代码高亮、表格美化，可一键导出 Word/PDF
📝 Markdown → Word	智能表格列宽、标题层级、引用块样式，打印友好
📑 Markdown → PDF	浏览器引擎打印，和网页视觉一致
🎞️ 图片 → 幻灯片	全屏播放、键盘翻页、自动轮播、缩略图导航
📦 幻灯片 → PDF	每张图片一页，适合存档分享

效果展示

💡 适用场景

🏢 AI Agent 生成报告/方案 → 一键变成可以直接发给客户的 PDF 或 Word
📄 Claude / GPT 输出的长文档 → 不用手动复制到 Word 调格式，自动排版
🎨 AI 生图工具批量出图 → 一键做成全屏幻灯片，现场演示或存档分享
⚙️ 团队内部 AI 工作流 → MCP 接入后 Agent 自动输出专业文档，零人工干预

📦 安装

需要 Node.js 18+，终端输入 node -v 检查，没有去 https://nodejs.org 下载。

AI Agent（如 Claude Code）帮你安装时，请优先使用方式一，避免权限和 PATH 问题。

方式一：npx 免安装（推荐，零配置）

npx agent-reader doctor              # 验证环境
npx agent-reader open README.md      # 立刻看到漂亮网页

不需要全局安装，不会遇到权限和 PATH 问题，拿来就用。

方式二：全局安装

npm install -g agent-reader

安装后验证：agent-reader doctor，全是 ✓ 就装好了。

开发模式：clone 仓库后 npm install && npm link

遇到问题？以下是两个最常见的坑：

权限错误（EACCES）

# 方法 1：加 sudo（简单粗暴）
sudo npm install -g agent-reader

# 方法 2：改 npm 全局目录（推荐，一劳永逸）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g agent-reader

安装成功但 command not found

npm 全局 bin 目录不在 PATH 中。先查路径，再加到 shell 配置：

npm bin -g                            # 查看 npm 全局 bin 路径
# 把输出的路径加到 ~/.zshrc 或 ~/.bashrc，例如：
echo 'export PATH=$(npm bin -g):$PATH' >> ~/.zshrc
source ~/.zshrc

🦞 OpenClaw 快速接入

OpenClaw 用户？30 秒接入，立刻获得文档美化能力。

一步接入（MCP 直连）

在你的 MCP 配置中添加：

{
  "mcpServers": {
    "agent-reader": {
      "command": "npx",
      "args": ["-y", "agent-reader", "mcp"]
    }
  }
}

接入后你可以直接对 OpenClaw 说：

你说	OpenClaw 调用	结果
"帮我把这个 Markdown 做成 PDF"	`export_document`	生成 PDF 文件
"整理成 Word 发给客户"	`export_document`	生成 DOCX 文件
"做成网页给我看看"	`render_markdown`	生成带目录的网页
"把这些图片做成幻灯片"	`create_slideshow`	生成全屏幻灯片
"幻灯片导出 PDF"	`export_slideshow`	每张图一页 PDF
"打开这个文件"	`open_file`	按偏好自动处理

完整工具参数、输入输出示例、错误处理说明见 SKILL.md，OpenClaw 专用 schema 见 openclaw-skill/。

🤖 给其他 AI Agent 用

MCP Server

兼容 Claude Desktop、Cline 等所有支持 MCP 协议的 AI Agent 框架。

Claude Desktop 配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "agent-reader": {
      "command": "node",
      "args": ["/path/to/agent-reader/src/mcp/server.js"]
    }
  }
}

提供 7 个 MCP 工具：

工具	功能
`render_markdown`	Markdown → 网页预览
`export_document`	Markdown → PDF / Word
`create_slideshow`	图片目录 → 幻灯片
`export_slideshow`	图片目录 → 幻灯片 HTML / PDF
`open_file`	智能打开（按偏好自动选格式）
`configure_user_preferences`	设置默认偏好
`get_user_preferences`	读取当前偏好

所有工具支持 return_content 参数，可直接返回文件内容（适合沙箱/Docker 环境）。

CLI Agent 模式

加 --profile agent，输出纯 JSON：

agent-reader render report.md --profile agent
# {"path":"...","format":"html","size":12345,"warnings":[]}

agent-reader export report.md --format docx --profile agent
# {"path":"...","format":"docx","size":8765,"warnings":[]}

🛠️ 手动使用（可选）

以下是人工操作 CLI 的方式。大多数情况下 Agent 会自动调用，你不需要手动敲命令。

🐣 小白模式

只需记住一个命令：agent-reader open 文件路径

agent-reader setup --default-open web    # 设置默认网页打开
agent-reader open 报告.md               # 按偏好自动处理
agent-reader open 报告.md --as word     # 临时指定 Word
agent-reader open ./图片文件夹/ --as ppt --auto 5

常用命令

agent-reader render 你的文件.md              # 预览网页
agent-reader render 你的文件.md --theme dark # 暗色主题
agent-reader export 你的文件.md --format docx # 导出 Word
agent-reader export 你的文件.md --format pdf  # 导出 PDF
agent-reader slides ./图片文件夹/             # 幻灯片
agent-reader slides ./图片文件夹/ --auto 5    # 自动轮播
agent-reader slides ./图片文件夹/ --format pdf # 幻灯片导出 PDF
agent-reader clean                            # 清理临时文件
agent-reader doctor                           # 检查环境

✨ 技术亮点

🎯 统一视觉源：HTML 是 PDF 的视觉基线（Puppeteer 打印），DOCX 保证结构一致
📊 智能表格列宽：根据内容长度自动计算比例，中文不会被挤压断行
🔒 安全默认：HTML sanitize 防 XSS、CSP 策略、SSRF 防护（禁止内网 IP）
🚀 零配置可用：Pandoc 缺失自动降级、端口冲突自动递增、临时文件自动隔离
🔄 双模式输出：human 模式自动打开 + 本地服务；agent 模式纯 JSON 输出

📋 依赖说明

依赖	必需？	用途
Node.js 18+	是	运行环境
Puppeteer	否（按需）	PDF 导出（可选依赖；未安装时仅影响 PDF）
Pandoc	否	Word 导出更好看（没有会自动降级为纯 JS 方案）

☁️ 云环境部署

在 Docker/CI 中，Agent Reader 会自动检测环境并在需要时为 Puppeteer 关闭沙盒参数。auto 模式首次失败时也会自动重试 no-sandbox。

# 手动覆盖：auto | on | off
AGENT_READER_SANDBOX=off agent-reader export report.md --format pdf

❓ FAQ

没有 Pandoc 怎么办？

不装也能导出 DOCX，只是排版简单一些。装了效果更好：

brew install pandoc        # macOS
apt-get install pandoc     # Linux
winget install pandoc      # Windows

Puppeteer 太重？

可以跳过 Chromium 下载，用系统浏览器：

PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install -g agent-reader
PUPPETEER_EXECUTABLE_PATH=/path/to/chrome agent-reader export report.md --format pdf