用途
PDF Card MCP 面向你确实需要阅读、引用或检查的 PDF。它把冗长文档拆分成更小的、与来源关联的卡片，将表格、图表、公式保留为忠实原样的图片裁剪，并允许你把笔记和高亮导出为 Markdown。
主要能力
- 本地优先：默认转换在本地运行，不需要托管服务。确定性转换器不上传文档内容，也不调用外部 API。
- 来源保留：保留源文本，渲染源页面以供核验，并为卡片建立来源关联。
- 图像裁剪：对检测到的表格、图表和展示公式进行图像裁剪，保持版面与数字对齐、上下标、箭头和数学间距。
- 样式派生：从原 PDF 调色板派生安全的阅读器样式。
- 独立输出：写出可跨设备移动且不丢失资源的独立 HTML 文件。
- 阅读体验：默认阅读器具备大字号、小卡片、搜索、章节导航、上一页/下一页控件、键盘导航、字号滑块和源页预览。
- 标注：支持高亮（选中源文本）和笔记（选中源文本加自己的笔记文本），并可导出为
.annotations.md。 - 静态发布：可生成带公开标注的只读静态阅读器。
使用方式
一键安装
PDF Card MCP 是 Python 服务器，需要运行时。唯一需要先安装的是 uv——它替你管理 Python。
Claude Code（终端）通过 uv 运行已发布的 pdf-card-mcp 包。
Claude Desktop（无需终端、无需前置条件）：从最新 release 下载 pdf-card-mcp-desktop.mcpb 并双击安装为扩展。该 bundle 声明了 uv 运行时，因此 Claude Desktop 会为你安装 Python 和依赖。
安装后，重启（或重新加载 MCP 服务器）你的客户端以使其识别新服务器。
命令行转换
将本地 PDF 转换为一个可移植的 HTML 阅读器；也可使用显式子命令形式并结合 PDF 派生样式。
运行 MCP 服务器
让兼容的宿主从本地 PDF 路径生成阅读器。
发布静态阅读器
发布一个带选定公开标注的只读静态阅读器。
其他安装方式
从 PyPI 安装；或直接从仓库安装最新未发布更改；本地开发；uv 推荐用于 MCPB 打包。
安装可选本地 ML 表格检测器以获得更强的表格裁剪。
在 MCP 客户端中使用
通过 uvx 添加到 Claude Code 或其他兼容 CLI 的 MCP 客户端（需要 uv）。也可使用通用 MCP 宿主配置。PyPI 发布前进行本地开发时，可将客户端指向此 checkout。Claude Desktop 也可从最新 GitHub release 安装 .mcpb bundle。
Docker / 注册表扫描器
仓库包含一个最小 Dockerfile，以便 Glama 等注册表构建服务器、通过 stdio 启动并检查其 MCP 工具 schema。服务器仍作用于本地文件路径，因此容器用户必须挂载希望工具读写的 PDF 和输出目录。
输出
document.html：独立阅读器，内嵌 CSS、JavaScript、表格裁剪、图表裁剪、公式裁剪和源页图像。 document.manifest.json：不含内嵌图像负载的结构化元数据。
笔记、高亮与静态发布
生成的阅读器包含本地标注覆盖层：高亮是选中的源文本；笔记是选中的源文本加你自己键入的笔记文本。在文本卡片中选择文本，选择 Highlight 或 Note，使用 Export Markdown 下载可读的 .annotations.md 文件。阅读器 UI 目前有意不暴露导入功能。笔记和高亮是用户创作的数据，与源派生的 document.manifest.json 分开保存。
更低层的 CLI 和 MCP 发布工具仍接受结构化标注 bundle，用于构建带内嵌标注的只读静态阅读器。可针对某个阅读器校验该 bundle，并发布可分享的静态阅读器。若 --output 是目录而非 .html 文件，命令会写出静态 bundle：reader.manifest.json 和 reader.annotations.json。
发布默认仅包含 visibility: public 的标注，默认隐匿本地 source_pdf 路径，默认将发布的阅读器渲染为只读。仅当你有意在发布输出中包含私有本地笔记时才使用 --include-private。若任何被包含的标注无法锚定到阅读器，发布会失败；发布前可运行 validate-annotations 检查不匹配。
MCP 工具
MCP 服务器是围绕同一本地转换器的自动化层，接受来自 MCP 客户端的本地文件路径，返回生成的阅读器路径、manifest 元数据、警告以及发布/校验结果。服务器暴露三个工具：
- 转换工具参数包括：pdf_path（本地 PDF 路径）；output_path（可选 HTML 输出路径）；title（可选标题覆盖）；standalone（默认 true，资源文件夹输出保留到后续版本）；ocr（可选 OCR 回退，需安装 pytesseract）；max_pages（可选处理上限）；theme（默认 soft）；style_engine（fixed、pdf 或 sampling，默认 pdf。fixed 保留原始 soft 调色板，pdf 从源 PDF 本地派生有界颜色与排版提示，sampling 让宿主 LLM 从这些本地提示中选择经校验的样式 token）；table_engine（auto、pdfplumber 或 gmft，auto 在安装 gmft 时使用它）；text_engine（char_geometry 或 pdfplumber_words，默认 char_geometry，从 PDF 字符位置修复缺失空格，而非信任粘连词）；postprocess_engine（none 或 sampling，默认 none。设为 sampling 时，MCP 服务器让宿主 LLM 执行仅边界层面的卡片润色操作，校验原文精确保留，并重写生成的阅读器。若 MCP 客户端不支持 sampling，则返回确定性输出并给出警告）；model_cache_dir（可选，本地 ML 表格模型权重的缓存目录）；offline（仅使用已缓存的可选 ML 模型）。
- validate_reader_annotations：针对生成的阅读器校验笔记/高亮 sidecar。
- publish_reader_bundle：从现有的生成阅读器和可选标注 sidecar 写出可发布的静态 HTML 文件或目录 bundle。
Sampling 后处理被刻意收窄。对于卡片边界，宿主 LLM 可建议合并、标题提取或前置内容/脚注分类，但 Python 校验会拒绝任何重写、删除、捏造或重排源文本的操作。对于 style_engine=sampling，宿主 LLM 只能选择有界样式 token 和调色板候选 ID；不能返回原始 CSS、JavaScript 或任意颜色。若 sampling 不可用，阅读器保留确定性的 PDF 派生样式并返回警告。
打包
仓库的排列方式使根目录可直接打包。构建产出三个 bundle：dist/pdf-card-mcp-lite.mcpb 和 dist/pdf-card-mcp.mcpb 声明 server.type = "python"，以兼容 MCP registry 和 Smithery 目录；完整 bundle 额外安装 table-ml extra。它们通过 uv 执行，因此宿主（或用户）必须提供 uv。dist/pdf-card-mcp-desktop.mcpb 声明 server.type = "uv"（来自 manifest.uv.json）。Claude Desktop 自行管理 Python 和依赖，因此终端用户可双击安装、无需前置条件。
任何 bundle 都不内置 ML 模型权重；除非设置 offline=true 并使用预热缓存，gmft 会在首次使用时本地下载并缓存它们。
隐私
默认 PDF 处理在本地进行。确定性转换器不上传文档内容或调用外部 API。可选 OCR 在用户安装 OCR 依赖后本地运行。当通过 MCP 启用 style_engine=sampling 或 postprocess_engine=sampling 时，宿主 LLM 可能收到有界样式提示或卡片文本片段，以返回经校验的样式 token 或边界操作计划。若不应让任何文档派生文本离开本地进程，请使用确定性的 fixed / pdf 样式和 postprocess_engine=none。
发布的阅读器可能包含提取的 PDF 文本、源页图像、表格/图表/公式裁剪，以及任何被包含的公开笔记或高亮。仅当你拥有分享源文档内容及标注的权利时才发布生成的阅读器。
关于转换流水线的自包含可视化说明（包括页面渲染、表格/图表裁剪、重叠抑制、文本卡片合并和独立 HTML 输出），见 docs/how-it-works.html。
表格处理方式
所有检测到的表格都渲染为图像卡片。转换器使用 pdfplumber 查找表格区域，并可选使用 gmft / Table Transformer 获得更强的本地检测。随后使用 pypdfium2 仅将源表格区域栅格化为 PNG。标题保留为阅读器文本和 alt 文本，但表格本身保持为图像，以便版面和数字对齐在转换后得以保留。
如果文档提到表格但未找到可靠表格区域，manifest 会包含一个警告，以便调用者决定是否检查源页。
公式处理方式
当 PDF 将展示公式暴露为居中、类似公式的文本块时，展示公式被当作图像卡片处理。提取的公式字符串保留用于 alt/搜索元数据，但阅读器显示源裁剪，以保持上下标、上标、箭头和数学间距忠实原样。
当前限制
这是一个早期开源实现。目前适用于具有文本层的 PDF，通过 pdfplumber 尽力进行表格检测，通过 pypdfium2 进行宽松的光栅渲染，并可选通过 gmft 进行更丰富的本地表格检测。扫描版 PDF 需要可选 OCR 支持。
