Local-first PDF processing MCP server — OCR write-back, text extraction, page rendering, page surgery, encryption (OCRmyPDF + Poppler + qpdf)
Server has 25 tools with consistent naming (verb_noun pattern: tool_pdf_info, tool_extract_text, etc.) and descriptions present for all. However, descriptions are often terse (10-50 chars) and lack LLM-optimized guidance on WHEN to use each tool or prerequisites. Parameter schemas are visible and typed, but many lack detailed descriptions (e.g., 'Page range' without format examples). Output schemas are not documented. Error handling via _guard wrapper is present but generic, does not guide recovery or categorize errors as retryable/user-fixable. No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels (READ_ONLY, WRITE, DESTRUCTIVE). Composition is good, tools are single-purpose and chainable (e.g., is_searchable → extract_text or ocr_pdf). Security: no secrets in params, but no audit logging visible.
批量 OCR 写回:inputs 为文件路径或目录(取全部 PDF)。单文件失败不中断,逐文件返回结果。
结构体检(语法/流编码);repair=true 尝试重建输出修复版文件。
压缩 PDF(ghostscript 有损)。给定 target_mb 时沿档位阶梯(ebook→screen)下探直到达标(尽力而为)。
检查系统依赖与能力级别(L0–L3)。
诊断系统环境与依赖完整性。
编辑 PDF 元数据(标题、作者、主题等)。
抽取 PDF 内嵌附件文件到指定目录;overwrite=true 才允许覆盖同名文件。
Descriptions lack LLM-optimized guidance. Most are 10 - 75 chars, below the 50 - 200 char baseline for A-grade tools. Missing WHEN to use, prerequisites, and dependencies (e.g., 'Call tool_is_searchable first to decide between extract_text and ocr_pdf').
Parameter descriptions are generic or missing detail. E.g., 'Page range like 1-3,5' appears in 6+ tools but never specifies: are 0-indexed or 1-indexed? Can you use 'all'? What happens if range exceeds page count? Format validation rules are implicit.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 59 | 2026-07-28+ | v2 |
抽取 PDF 内嵌图片为 PNG;list_only=true 只返回图片清单不落盘。 overwrite=true 才允许覆盖同名图片。
提取 PDF 文本(pdftotext)。pages 精确页范围如 '1-3,5';layout 保持版面;per_page 按页返回。
填写 AcroForm 表单字段。
智能路由入口:判断 PDF 是否已有可提取文本层,返回建议动作(extract_text 或先 ocr_pdf)。不确定时先调这个。
Web 优化:输出渐进加载版,适合在线浏览的发布文件。
字体体检:列出字体与嵌入状态,未嵌入字体跨设备查看/打印可能缺字。
定位文本出现的页面与坐标框(PDF 点、左上原点)——找内容在哪、给 redact 量坐标的地基。 中文无分词、英文跨词均可命中(NFKC 归一化去空白匹配)。
按传入顺序合并多个 PDF 为一个文件。
对扫描件 OCR 并把文本层写回,产出可搜索 PDF(输出 <stem>_ocr.pdf)——本工具箱的核心差异化能力。 默认跳过已有文本层的页;默认语言 chi_sim+eng(缺语言包时自动降级并在结果中说明)。
获取 PDF 元信息:页数、是否加密、页面尺寸、标题作者等。处理任何 PDF 前先调用此工具。
AES-256 加密(对外分发)。user_password 留空 = 打开无密码、仅权限限制;权限默认可打印可复制、不可修改。
真涂黑(安全级):regions=[{page,x,y,w,h}](PDF 点、左上原点)。含涂黑区域的页被光栅化—— 被涂文字物理删除,复制/提取/文本层均无法恢复;其余页保留原文本层。 rasterize_all=true 全文档光栅化(最高防护档)。
按内容真涂黑:自动定位每个 query 的全部出现处并涂黑。
渲染指定页为 PNG。return_images=True 时直接返回图像内容块(供视觉查看复杂版面/图表/扫描页)。
旋转页面 90/180/270 度。pages 缺省旋转全部页。
发布版脱敏:剥离 JS/OpenAction/元数据/附件(可选注释)。正文文本不动——防元数据与隐藏对象泄密。
拆分 PDF:ranges='1-3,5' 按区间出文件,或 every_n=N 每 N 页一段。二者二选一。
用密码解锁加密 PDF,输出解密文件。user(打开)密码即可,无需 owner 密码。解锁后再走其他工具。
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels declared (READ_ONLY, WRITE, DESTRUCTIVE). Agents cannot infer safety properties from tool definitions alone.
Output schemas not documented. Tools return dicts with fields like 'ok', 'error', '_deps', 'images', 'pages', etc., but no schema is published. LLMs cannot plan downstream calls or extract fields reliably.
Error handling is generic. _guard wrapper returns {'ok': False, 'error': <code>, 'message': ...} but does not categorize errors as retryable/user-fixable/fatal or provide recovery guidance (e.g., 'missing_dependency → see install field' is mentioned in instructions but not in error responses).