PDF Card MCP

PDF Card MCP

PDF Card MCP 是一款本地优先的 MCP 服务和命令行工具，可将内容密集的本地 PDF 转换为便于携带、链接到原文的 HTML 阅读器。MCP 主机可以让它转换 PDF 路径、验证笔记和高亮，或发布静态的注释阅读器包。转换器会保留原文文本、渲染原始页面以供核验，将检测到的表格、插图和展示公式裁剪为图像，根据原始 PDF 配色生成安全的阅读器样式，并写出独立的 HTML 文件，可在不同设备间移动而不会丢失资源。

默认转换完全在本地运行，无需托管服务。可选的 MCP 采样受到严格限制：主机模型可以选择经过验证的样式标记，或建议优化卡片边界的操作，但原始 CSS 和对源文本的改写会被拒绝。

默认阅读器专为舒适阅读而设计：大字号、小卡片、搜索、章节导航、上一页／下一页控件、键盘导航、字号滑块和原文页面预览。

PDF Card MCP 面向你确实需要阅读、引用或检查的 PDF。它会将长文档转换为更小且链接到原文的卡片，以忠实的图像裁剪保留表格、插图和公式，并允许你将自己的笔记和高亮导出为 Markdown。

快速安装（单击即可）

PDF Card MCP 是一个 Python 服务，因此需要运行环境。首先只需安装 uv——它会帮你管理 Python，无需手动处理。以下所有安装方式都只需要这一项前置条件：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

然后单击按钮即可添加服务。按钮会通过 uv 运行已发布的 pdf-card-mcp 包：

Claude Code（终端）：

claude mcp add pdf-card -- uvx --from pdf-card-mcp pdf-card-mcp-server

Claude Desktop（无需终端或前置条件）：从最新版本下载 pdf-card-mcp-desktop.mcpb，然后双击将其安装为扩展。此安装包声明了 uv 运行环境，因此 Claude Desktop 会为你安装 Python 和依赖项——采用此方式时，无需执行上面的 uv 步骤。

安装后，请重启客户端（或重新加载其中的 MCP 服务），以便客户端加载新服务。

真实截图

这些截图展示了为 Agents in Software Engineering 生成的阅读器，以及并排打开的同一份源 PDF，便于对比。

生成的阅读器	原始 PDF

快速示例

将本地 PDF 转换为一个便携式 HTML 阅读器：

pdf-card-mcp ./paper.pdf --output ./out/paper-reader.html

使用显式子命令形式，并应用从 PDF 提取的样式：

pdf-card-mcp convert ./paper.pdf \
  --output ./out/paper-reader.html \
  --style-engine pdf

运行 MCP 服务，让兼容的宿主根据本地 PDF 路径生成阅读器：

python -m pdf_card_mcp.server

发布带有选定公开批注的只读静态阅读器：

pdf-card-mcp publish ./out/paper-reader.html \
  --annotations ./paper.annotations.json \
  --output ./published/paper-reader.html

输出一览

输出	内容
paper-reader.html	独立阅读器，内嵌 CSS、JavaScript、页面图像和检测到的裁剪内容。
paper.manifest.json	卡片、页面、警告和源锚点的结构化元数据。
Markdown 导出	来自阅读器 UI 的用户笔记和高亮内容。
已发布的资源包	用于分享公开批注的只读静态 HTML 或目录资源包。

状态

这是一个早期的开源实现。目前适用于带文本层的 PDF，并通过 pdfplumber 尽力检测表格、使用 pypdfium2 进行宽松的光栅渲染，还可选用 gmft 在本地进行更丰富的表格检测。扫描版 PDF 需要可选的 OCR 支持。

安装

大多数人应使用上文的一键安装。如需直接从 PyPI 安装软件包：

python -m pip install pdf-card-mcp

或者直接从代码仓库安装最新的未发布更改：

python -m pip install "pdf-card-mcp @ git+https://github.com/velyan/pdf-card-mcp.git"

用于本地开发：

git clone https://github.com/velyan/pdf-card-mcp.git
cd pdf-card-mcp
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e ".[dev]"

MCPB 打包推荐使用 uv：

uv sync
uv run pdf-card-mcp path/to/document.pdf --output out/document.html

如需更准确地裁剪表格，可安装可选的本地 ML 表格检测器：

uv sync --extra table-ml
uv run --extra table-ml pdf-card-mcp path/to/document.pdf --table-engine gmft

在 MCP 客户端中使用

使用 uvx 将其添加到 Claude Code 或其他兼容 CLI 的 MCP 客户端中（需要 uv）：

claude mcp add pdf-card -- uvx --from pdf-card-mcp pdf-card-mcp-server

通用 MCP 宿主配置：

{
  "mcpServers": {
    "pdf-card": {
      "command": "uvx",
      "args": ["--from", "pdf-card-mcp", "pdf-card-mcp-server"]
    }
  }
}

在 PyPI 发布前进行本地开发时，将客户端指向此代码检出目录：

{
  "mcpServers": {
    "pdf-card-local": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/pdf-card-mcp",
        "run",
        "python",
        "-m",
        "pdf_card_mcp.server"
      ]
    }
  }
}

Claude Desktop 也可以从最新的 GitHub 发布版本安装 .mcpb 资源包。

Docker / 注册表扫描器

代码仓库中包含一个最精简的 Dockerfile，因此 Glama 等注册表可以构建服务、通过 stdio 启动服务，并检查其 MCP 工具架构。该服务仍通过本地文件路径工作，因此容器用户必须挂载希望工具读取或写入的 PDF 和输出目录：

docker build -t pdf-card-mcp .
docker run --rm -i \
  -v "$PWD/examples:/docs" \
  pdf-card-mcp

CLI 用法

pdf-card-mcp path/to/document.pdf --output examples/out/document.html

该命令会写入：

• document.html：独立阅读器，内嵌 CSS、JavaScript、表格裁剪图、插图裁剪图、公式裁剪图和源页面图像。
• document.manifest.json：不含内嵌图像数据的结构化元数据。

也支持显式子命令形式：

pdf-card-mcp convert path/to/document.pdf --output examples/out/document.html

注释、高亮和静态发布

生成的阅读器包含本地注释层：

• 高亮是选中的源文本。
• 笔记是选中的源文本加上你输入的笔记文本。

在文本卡片中选择文本，选择 Highlight 或 Note，然后使用 Export Markdown 下载易于阅读的 .annotations.md 文件。目前阅读器界面尚未开放导入功能。笔记和高亮由用户编写，并与源文件派生的 document.manifest.json 分开保存。

如果需要构建嵌入注释的只读静态阅读器，底层 CLI 和 MCP 发布工具仍接受结构化注释包。使用阅读器验证该注释包：

pdf-card-mcp validate-annotations examples/out/document.html document.annotations.json

发布包含公开注释、可供分享的静态阅读器：

pdf-card-mcp publish examples/out/document.html \
  --annotations document.annotations.json \
  --output published/document-reader.html

如果 --output 是目录而非 .html 文件，该命令会写入一个静态包：

• index.html
• reader.manifest.json
• reader.annotations.json
• bundle.json

默认情况下，发布只包含 visibility: public 注释，会隐藏本地 source_pdf 路径，并将已发布的阅读器设为只读。仅当你确实想在发布内容中包含本地私有笔记时，才使用 --include-private。如果任何待包含的注释都无法锚定到阅读器，发布就会失败；发布前运行 validate-annotations 检查不匹配项。

MCP 工具

MCP 服务是围绕同一本地转换器构建的自动化层。它接受 MCP 客户端提供的本地文件路径，并返回生成的阅读器路径、清单元数据、警告以及发布/验证结果。

该服务提供三种工具：

convert_pdf_to_card_html
validate_reader_annotations
publish_reader_bundle

输入：

• pdf_path：本地 PDF 路径。
• output_path：可选的 HTML 输出路径。
• title：可选的标题覆盖值。
• standalone：默认为 true；资源文件夹输出预留给后续版本。
• ocr：如果已安装 pytesseract，则可选用作 OCR 回退方案。
• max_pages：可选的处理页数限制。
• theme：默认为 soft。
• style_engine：fixed、pdf 或 sampling；默认为 pdf。fixed 保留原始的柔和配色，pdf 在本地根据源 PDF 提取有限范围内的颜色和排版提示，而 sampling 会让宿主大模型根据这些本地提示选择经过验证的样式令牌。
• table_engine：auto、pdfplumber 或 gmft；auto 会在安装了 gmft 时使用它。
• text_engine：char_geometry 或 pdfplumber_words；默认为 char_geometry，这样会根据 PDF 字符位置修复缺失的空格，而不是依赖粘连的词语。
• postprocess_engine：none 或 sampling；默认为 none。设为 sampling 时，MCP 服务会请求宿主大模型执行仅限边界调整的卡片润色操作，验证是否精确保留源文本，并重写生成的阅读器。如果 MCP 客户端不支持 sampling，则会返回确定性输出并附带警告。
• model_cache_dir：本地 ML 表格模型权重的可选缓存目录。
• offline：仅使用已缓存的可选 ML 模型。

validate_reader_annotations 会根据生成的阅读器检查笔记/高亮侧车文件。publish_reader_bundle 会根据已有的生成阅读器和可选注释侧车文件，写入可供发布的静态 HTML 文件或目录包。

采样后处理的范围刻意限定得很窄。对于卡片边界，宿主大模型可以建议合并、提取标题，或分类前置内容/脚注；但 Python 验证会拒绝任何改写、删除、编造或重新排序源文本的操作。对于 style_engine=sampling，宿主大模型只能选择有限范围内的样式令牌和调色板候选 ID；不能返回原始 CSS、JavaScript 或任意颜色。如果无法使用 sampling，阅读器会保留由 PDF 确定性推导的样式，并返回警告。

在本地运行服务：

python -m pdf_card_mcp.server

MCPB 打包

此仓库经过安排，可直接从根目录打包：

python scripts/build_mcpb.py --variant all

这会构建三个包：

• dist/pdf-card-mcp-lite.mcpb 和 dist/pdf-card-mcp.mcpb 声明 server.type = "python"， 以兼容 MCP registry 和 Smithery 目录。完整包还会安装 table-ml extra。这些包通过 uv 运行，因此主机（或用户）必须提供 uv。
• dist/pdf-card-mcp-desktop.mcpb 声明 server.type = "uv"（来自 manifest.uv.json）。Claude Desktop 会自行管理 Python 和依赖，因此最终用户无需任何前置条件，双击即可安装。这是上文 一键安装部分链接的包。

这些包都不包含机器学习模型权重；除非设置 offline=true 并使用已预热的缓存，否则 gmft 会在首次使用时下载并在本地缓存模型权重。

隐私

PDF 默认在本地处理。确定性转换器不会上传文档内容，也不会调用外部 API。用户安装 OCR 依赖后， 可选择在本地运行 OCR。

通过 MCP 启用 style_engine=sampling 或 postprocess_engine=sampling 时，主机 大模型可能会收到有限的样式提示或卡片文本片段，以便返回经过验证的样式令牌 或边界操作方案。若不希望任何源自文档的文本离开本地进程，请使用确定性的 fixed/pdf 样式和 postprocess_engine=none。

发布的阅读器可能包含提取的 PDF 文本、源页面图像、表格／图形／公式裁剪图，以及其中包含的任何公开说明或高亮内容。仅当你有权分享源文档内容及其批注时，才发布生成的阅读器。

工作原理

请参阅 docs/how-it-works.html，了解转换流程的独立可视化说明， 其中包括页面渲染、表格／图形裁剪、重叠抑制、文本卡片合并以及独立 HTML 输出。

表格处理方式

所有检测到的表格都会渲染为图像卡片。转换器使用 pdfplumber 查找表格区域，也可选择使用 gmft/Table Transformer 来增强本地检测效果。随后使用 pypdfium2 仅将源文件中的表格区域 栅格化为 PNG。标题会保留为阅读器文本和替代文本，而表格本身仍以图像呈现，以保留版式和数字对齐。

如果文档提到了表格，但未找到可靠的表格区域，清单中会包含一条警告，以便调用方决定是否检查源页面。

公式处理方式

如果 PDF 将显示公式呈现为居中且类似公式的文本块，系统就会将其作为图像卡片处理。提取的公式字符串会保留为替代文本／搜索元数据，但阅读器会显示源裁剪图，以忠实保留下标、上标、箭头和数学排版间距。

许可证

MIT