关于 PDF SPEC MCP Server
PDF SPEC MCP Server 为 LLM 提供对 ISO 32000 等 PDF 相关规范的结构化访问,适用于需要搜索条款、提取要求或比较 PDF 版本的开发者和标准研究者。它检索规范文本,但不检查或验证 PDF 文件。
主要功能
- 01发现支持的规范文档
- 02浏览章节结构和内容
- 03搜索规范全文
- 04提取规范性要求和定义
- 05提取表格并比较 PDF 版本
- 06在磁盘缓存搜索索引
适用场景
- 01查找 PDF 标准中的条款
- 02核对规范性要求的措辞
- 03查询规范术语的定义
- 04比较 PDF 1.7 与 PDF 2.0 的结构
MCP 相关
向 MCP 客户端提供规范发现、浏览、搜索、提取和比较工具。用户需在本地提供规范 PDF 文件;服务端不会检查 PDF 是否符合规范。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
8收录的工具列表 · 更新于 2 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| category | string | 否 | 按类别筛选(standard、ts、pdfua、guide、appnote)。 |
详细介绍
PDF SPEC MCP 服务
这是一个 MCP(Model Context Protocol)服务,可提供对 ISO 32000(PDF)规范文档的结构化访问。通过定义明确的工具,帮助大模型浏览、搜索和分析 PDF 规范。
重要
这是规范的参考资料,不是规则引擎。 它会检索并整理 ISO 32000 的文本,包括条款、表格、定义以及
shall/should/may要求。它不会检查 PDF 文件,也无法判断文档是否符合任何标准。符合性判定应由 pdf-verify-mcp (validate_conformance/evaluate_policy)提供。这里有三种容易混淆的不同概念: 声明——文件对自身的标注(例如在元数据中写“我是 PDF/A”)。写上这类标注并不能作为证据 / 符合性——文件是否实际满足标准。无法对其进行完整证明;你只能找出违反规则之处 / 验证——验证器(例如 veraPDF)根据其实现的检查项得出的报告。通过意味着“此次检查未发现失败”,而不是“文件符合标准”。 在此处读取一条
shall要求,只能了解标准的要求,不能据此判断你的文件是否满足要求。搜索无结果意味着“无法回答”,而不是“不存在此类要求”。 ISO 19005(PDF/A)和 ETSI PAdES 不在此语料库中;请查看
list_specs→coverage.gaps。
各 PDF 系列服务的功能与限制
| 服务 | 功能 | 不提供 |
|---|---|---|
| pdf-spec-mcp(本服务) | 搜索、检索并提取 17 份 PDF 相关文档中的要求 | **不是规则引擎。**不定义业务规则、不检查 PDF 文件,也不验证架构。ISO 19005(PDF/A)不在此语料库中 |
| pdf-reader-mcp | 提取文本 / 表格 / 结构树 / 字体 / 注释 / 图像 / 签名字段 | **不验证密码学。**不读取增量更新历史,不将对象 ID 映射到坐标,也不执行 OCR |
| pdf-writer-mcp | 创建 PDF、执行页面操作、添加标签、表单、注释、元数据和附件,以及创建 PDF/A-3b 基础结构 | **不签名。**不会使文件符合标准——它只能写入标注,不能保证符合性 |
| pdf-verify-mcp | 符合性验证(委托 veraPDF 执行)、加密签名验证、防篡改检测、策略判定 | 不能证明文件符合标准(只能找出违反规则之处)。不对签署者身份背书,也不判断内容是否属实 |
重要
此软件包不包含 PDF 规范文件。 你必须另行获取 PDF 规范文档,并将其放入本地目录。
下载地址:PDF Association — Sponsored Standards
详情请参阅“设置”。
功能
- 支持多种规范 — 自动发现并管理多达 17 份 PDF 相关文档(ISO 32000-2、PDF/UA、Tagged PDF 指南等)
- 结构化内容提取 — 提取任意章节中的标题、段落、列表、表格和注释
- 全文搜索 — 按关键词搜索,并提供感知章节结构的上下文片段
- 要求提取 — 按照 ISO 惯例提取规范性措辞(shall / must / may)
- 定义查询 — 从“术语和定义”条款中查询术语定义(ISO 32000-2 的第 3 条、ISO 32000-1 的第 4 条)
- 表格提取 — 检测跨页表格并合并表头
- 版本比较 — 比较 PDF 1.7 与 PDF 2.0 的章节结构差异
- 有界并发处理 — 并行处理大型文档的页面
- 磁盘索引缓存 — 每份 PDF 的搜索索引和完整要求扫描结果只构建一次,供后续每次运行复用(ISO 32000-2:约 6 秒 → 约 0.2 秒)
架构
graph LR
subgraph Client["MCP Client"]
LLM["LLM<br/>(Claude, etc.)"]
end
subgraph Server["PDF Spec MCP Server"]
direction TB
MCP["MCP Server<br/>index.ts"]
subgraph Tools["Tools Layer"]
direction LR
T1["list_specs"]
T2["get_structure"]
T3["get_section"]
T4["search_spec"]
T5["get_requirements"]
T6["get_definitions"]
T7["get_tables"]
T8["compare_versions"]
end
subgraph Services["Services Layer"]
direction LR
REG["Registry<br/>Auto-discovery"]
LOADER["Loader<br/>LRU Cache"]
SVC["PDFService<br/>Orchestration"]
CMP["CompareService<br/>Version Diff"]
end
subgraph Extractors["Extractors"]
direction LR
OUTLINE["OutlineResolver<br/>TOC & Section Index"]
CONTENT["ContentExtractor<br/>Structured Extraction"]
SEARCH["SearchIndex<br/>Full-text Search"]
REQ["RequirementExtractor"]
DEF["DefinitionExtractor"]
end
subgraph Utils["Utils"]
direction LR
CACHE["LRU Cache"]
CONC["Concurrency"]
VALID["Validation"]
end
end
subgraph PDFs["PDF Spec Files (obtained separately)"]
direction LR
PDF1["ISO 32000-2<br/>(PDF 2.0)"]
PDF2["ISO 32000-1<br/>(PDF 1.7)"]
PDF3["TS 32001–32005<br/>PDF/UA, etc."]
end
LLM <-->|"stdio / JSON-RPC"| MCP
MCP --> Tools
Tools --> Services
Services --> Extractors
Services --> Utils
LOADER --> PDFs
REG -->|"Filename pattern<br/>auto-discovery"| PDFs
style Client fill:#e8f4f8,stroke:#2196F3
style PDFs fill:#fff3e0,stroke:#FF9800
style Tools fill:#e8f5e9,stroke:#4CAF50
style Services fill:#f3e5f5,stroke:#9C27B0
style Extractors fill:#fce4ec,stroke:#E91E63
style Utils fill:#f5f5f5,stroke:#9E9E9E
各层概览
| 层 | 职责 |
|---|---|
| 工具 | MCP 工具架构定义和处理程序(输入验证) |
| 服务 | 业务逻辑(PDF 注册表、加载器、编排) |
| 提取器 | 从 PDF 中提取信息(目录、内容、搜索、要求、定义) |
| 实用工具 | 共享实用工具(缓存、并发、验证) |
设置
1. 获取 PDF 规范文件
警告
PDF 规范属于受版权保护的文档,本软件包不包含这些文档。 请从以下来源下载,并将其放入本地目录。
| 文档 | 来源 |
|---|---|
| ISO 32000-2(PDF 2.0) | PDF Association |
| ISO 32000-1(PDF 1.7) | Adobe(免费) |
| TS 32001–32005、PDF/UA 等 | PDF Association — 赞助标准 |
以下 17 份文件均受支持。无需全部准备,只需放入所需的规范文件即可(建议至少包含 ISO 32000-2)。
pdf-specs/
│
│ ── Standards ─────────────────────────────
├── ISO_32000-2_sponsored_EC3.pdf # iso32000-2 : PDF 2.0 EC3 (recommended; falls back to -ec2.pdf)
├── ISO_32000-2-2020_sponsored.pdf # iso32000-2-2020 : PDF 2.0 original
├── PDF32000_2008.pdf # pdf17 : PDF 1.7 (for version comparison)
├── pdfreference1.7old.pdf # pdf17old : Adobe PDF Reference 1.7
│
│ ── Technical Specifications (TS) ─────────
├── ISO_TS_32001-2022_sponsored_EC3.pdf # ts32001 : Hash extensions (SHA-3)
├── ISO_TS_32002-2022_sponsored_EC3.pdf # ts32002 : Digital signature extensions (ECC/PAdES)
├── ISO_TS_32003-2023_sponsored.pdf # ts32003 : AES-GCM encryption
├── ISO-TS-32004-2024_sponsored.pdf # ts32004 : Integrity protection
├── ISO-TS-32005-2023-sponsored.pdf # ts32005 : Namespace mapping
│
│ ── PDF/UA (Accessibility) ────────────────
├── ISO-14289-1-2014-sponsored.pdf # pdfua1 : PDF/UA-1
├── ISO-14289-2-2024-sponsored.pdf # pdfua2 : PDF/UA-2
│
│ ── Guides ────────────────────────────────
├── Tagged-PDF-Best-Practice-Guide.pdf # tagged-bpg : Tagged PDF Best Practice
├── Well-Tagged-PDF-WTPDF-1.0.pdf # wtpdf : Well-Tagged PDF
├── PDF-Declarations.pdf # declarations: PDF Declarations
│
│ ── Application Notes ─────────────────────
├── PDF20_AN001-BPC.pdf # an001 : Black Point Compensation
├── PDF20_AN002-AF.pdf # an002 : Associated Files
└── PDF20_AN003-ObjectMetadataLocations.pdf # an003 : Object Metadata
2. 安装
此软件包提供了一个 CLI 二进制文件(pdf-spec-mcp),供 MCP 客户端启动。
无需手动安装——只需按照下一步所示,将 MCP 客户端指向 npx @shuji-bonji/pdf-spec-mcp@latest。
如果要直接从 shell 运行(例如用于调试):
PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp@latest
也可以全局安装(可选):
npm install -g @shuji-bonji/pdf-spec-mcp
PDF_SPEC_DIR=/path/to/pdf-specs pdf-spec-mcp
3. 配置 MCP 客户端
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
PDF_SPEC_DIR | 存放 PDF 规范文件的目录 | (必填) |
PDF_SPEC_CACHE_DIR | 磁盘索引缓存的存放位置(参见索引缓存) | ${XDG_CACHE_HOME:-~/.cache}/pdf-spec-mcp |
PDF_SPEC_CACHE | 设为 off 时不读取也不写入索引缓存 | on |
Claude Desktop
添加到 claude_desktop_config.json:
{
"mcpServers": {
"pdf-spec": {
"command": "npx",
"args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
"env": {
"PDF_SPEC_DIR": "/path/to/pdf-specs"
}
}
}
}
重要
使用
@latest(或固定版本)。 不带版本号运行npx -y <pkg>,会持续运行它第一次缓存的版本——-y只会跳过安装提示,不会检查更新。 不指定版本时,它会毫不迟疑地运行几个月前的旧版本。使用@latest可让 npx 每次启动时检查注册表;如果需要确保结果可复现,则改用@0.4.0固定版本。 清除过期缓存:rm -rf ~/.npm/_npx。
Cursor / VS Code
添加到 .cursor/mcp.json 或 VS Code MCP 设置:
{
"mcpServers": {
"pdf-spec": {
"command": "npx",
"args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
"env": {
"PDF_SPEC_DIR": "/path/to/pdf-specs"
}
}
}
}
安装为 Claude Code 插件
插件清单(.claude-plugin/plugin.json)声明了 "PDF_SPEC_DIR": "${PDF_SPEC_DIR}",并依赖宿主替换该引用。并非所有宿主都会进行替换:
| 宿主 | 是否展开插件 env 中的 ${VAR} | 应改为在哪里填写绝对路径 |
|---|---|---|
| Claude Code(终端) | 是 | — |
| Grok Build 1.0.30 | 否 | ~/.grok/config.toml,[mcp_servers.pdf-spec] |
| Claude Desktop,与此电脑关联的云端会话(插件工具) | 否 | 桌面应用读取的本地 MCP 配置 |
如果引用原样传递,每个工具都会返回 REGISTRY_ERROR,其消息以 PDF_SPEC_DIR is the unexpanded text "${PDF_SPEC_DIR}" 开头,且第一个 next_actions 条目为 set_absolute_path_in_host_config。这是宿主配置问题,而不是目录缺失——将绝对路径写入宿主自己的配置并重启。
各宿主的操作步骤:https://shuji-bonji.github.io/pdf-agent-stack/reference/env-vars。
索引缓存
有两种操作会遍历规范的所有页面:首次对某个规范执行 search_spec 时会构建其全文索引(ISO 32000-2 共 1023 页:在笔记本电脑上约需 6 秒),而不带 section 的 get_requirements 会扫描所有章节(约需 11 秒)。其他操作只会打开所需页面,耗时远低于一秒。
从 0.5.0 开始,这两种操作的结果会在首次构建后写入磁盘,之后每个进程都会读取缓存——每个会话启动一个 MCP 服务的 MCP 客户端,不再需要每次重新构建。第二个进程可在约 0.2 秒内返回相同的 search_spec 结果,并在约 0.02 秒内完成完整的需求扫描;所用索引逐字节完全相同。
- 位置:
${PDF_SPEC_CACHE_DIR:-${XDG_CACHE_HOME:-~/.cache}/pdf-spec-mcp}/v1/<version>/<spec>.<kind>.<sha256[0:16]>.json。 17 个规范构成的完整语料库,每个软件包版本约占 18 MB。 - 键: 软件包版本、
pdfjs-dist版本、规范 ID 和 PDF 的 SHA-256。替换 PDF、升级服务或升级 pdfjs 都会导致缓存未命中并重新构建。旧版本的条目会保留(其他安装可能仍在使用);--clear-cache会删除所有内容。 - 失败只会导致缓存未命中,不会报错: 无法读取、已截断或格式不明的文件会被重新构建;如果目录不可写,会在 stderr 上报告一次,服务随后会在不使用缓存的情况下继续运行。
- 缓存由你自己的 PDF 副本生成,并保留在你的设备上。 它不是软件包的一部分,不得再分发——这些规范受版权保护。
搜索过程没有任何变化:仍由相同的代码搜索相同的内存结构。变化的只是数据来源(构建或读取)。
预构建缓存
缓存会在工具使用规范时逐个延迟填充。要提前预热所有规范——例如安装后、升级后或通过 cron 执行时——请运行 CLI(它使用与工具相同的代码路径,按顺序处理规范,然后退出):
PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp@latest --build-cache
# --spec=iso32000-2,pdf17 only these specs
# --force rebuild even when a valid entry exists
npx -y @shuji-bonji/pdf-spec-mcp@latest --cache-info # directory, key, entries
npx -y @shuji-bonji/pdf-spec-mcp@latest --clear-cache # remove the directory
在笔记本电脑上构建 17 个规范构成的完整语料库约需一分钟。
可用工具
所有工具均接受可选的 spec 参数,用于指定特定规范(默认为 iso32000-2)。
| 工具 | 描述 |
|---|---|
list_specs | 列出所有已发现的 PDF 规范及其元数据 |
get_structure | 获取章节层级(目录),深度可配置 |
get_section | 获取特定章节的结构化内容 |
search_spec | 在某项规范中进行全文关键词搜索 |
get_requirements | 提取规范性要求(shall/must/may) |
get_definitions | 查询术语定义 |
get_tables | 提取章节中的表格结构 |
compare_versions | 比较 PDF 1.7 和 PDF 2.0 的章节结构 |
list_specs — 发现规范
列出所有可用的规范文档。将返回的 ID 用作其他工具的 spec 参数。
// List all specs
{ }
// Filter by category
{ "category": "ts" } // Technical specs only
{ "category": "pdfua" } // PDF/UA only
{ "category": "guide" } // Guide documents only
get_structure — 目录
获取规范的章节层级(目录树)。
// PDF 2.0 top-level sections only
{ "max_depth": 1 }
// Expand to 2 levels
{ "max_depth": 2 }
// TS 32002 (Digital Signatures) full structure
{ "spec": "ts32002" }
// PDF/UA-2 structure
{ "spec": "pdfua2", "max_depth": 2 }
get_section — 章节内容
获取特定章节的结构化内容(标题、段落、列表、表格、注释)。
父章节会返回其整个子树(先是前言,再按文档顺序列出所有子章节)。顶层条款可能非常长——建议使用尽可能具体的章节编号。
每个回答都会包含 pageRange 和 boundary。boundary 说明内容两端的截断方式:
boundary.start | 含义 |
|---|---|
heading | 找到了该章节自身的标题;已删除第一页上标题之前的文本 |
page | 未找到标题;内容从第一页顶部开始,可能包含上一章节的末尾内容 |
boundary.end | 含义 |
|---|---|
heading | 在下一章节的标题处截断 |
page | 内容截至其最后一页;下一章节从后续页面开始 |
page_shared | 下一章节从最后一页开始,但未找到其标题——内容可能包含下一章节的文本 |
next_page_unclaimed | 下一章节从下一页开始,且未在该页找到其标题——本章节在该页的任何末尾内容均未包含 |
document | 文档的最后一个章节 |
除了 heading / heading、heading / page 或 heading / document 之外的任何情况,都表示内容在页面边界处截断:在依赖这些内容之前,也请读取相邻章节。对于父章节,start 指父章节自身的边界,end 指其最后一个后代章节的边界。
// PDF 2.0 Section 7.3.4.2 (Literal Strings)
{ "section": "7.3.4.2" }
// PDF 2.0 Annex A
{ "section": "Annex A" }
// TS 32002 Section 5
{ "spec": "ts32002", "section": "5" }
// PDF/UA-2 Section 8 (Tagged PDF)
{ "spec": "pdfua2", "section": "8" }
search_spec — 全文搜索
在规范中搜索,并提供包含章节上下文的摘录。首次调用某项规范时会建立索引(需要几秒);之后索引会缓存在磁盘上(参见索引缓存)。
// Search PDF 2.0 for "digital signature"
{ "query": "digital signature" }
// Limit results
{ "query": "font", "max_results": 5 }
// Search within TS 32002
{ "spec": "ts32002", "query": "CMS" }
get_requirements — 规范性要求
按照 ISO 惯例提取规范性要求(shall / must / may)。
sectionsCutByPage 列出范围内内容在页面边界处截断的章节(参见 get_section 下的 boundary);这些章节的要求可能包含相邻章节的句子,也可能遗漏末尾内容。如果范围内所有章节都在标题处截断,则该列表为空。
// All requirements in section 12.8
{ "section": "12.8" }
// Only "shall" requirements
{ "section": "12.8", "level": "shall" }
// Only "shall not" requirements
{ "section": "7.3", "level": "shall not" }
// PDF/UA-2 requirements
{ "spec": "pdfua2", "section": "8", "level": "shall" }
get_definitions — 术语定义
查询“术语和定义”条款中的术语定义——ISO 32000-2 的第 3 条(71 个术语),ISO 32000-1 / pdf17 的第 4 条(48 个术语)。每个结果中的 section 是文档中印刷的编号(3.12、4.11)。
// Search for "font" definitions
{ "term": "font" }
// List all definitions
{ }
// PDF/UA definitions
{ "spec": "pdfua2", "term": "artifact" }
get_tables — 表格提取
从一个章节中提取表格结构(表头、行、标题)。跨页表格会自动合并。
答案包含 pageRange(读取表格的页码范围)和 boundary(见 get_section)。totalTables: 0 表示这些页面中未找到 Table 元素——如果 boundary 指示页面截断,这些页面本身可能并未涵盖整个章节。
// All tables in section 7.3.4.2 (Table 3 — Escape sequences)
{ "section": "7.3.4.2" }
// Specific table only (0-based index)
{ "section": "7.3.4.2", "table_index": 0 }
// TS spec tables
{ "spec": "ts32002", "section": "5" }
compare_versions — 版本比较
比较 PDF 1.7(ISO 32000-1)与 PDF 2.0(ISO 32000-2)中的章节结构。使用基于标题的自动匹配,检测匹配、新增和已删除的章节。
说明
此工具要求
PDF_SPEC_DIR中同时包含 PDF 1.7(PDF32000_2008.pdf)和 PDF 2.0 文件。
// Diff section 12.8 (Digital Signatures)
{ "section": "12.8" }
// Compare all top-level sections
{ }
支持的规范
服务会根据文件名模式自动发现 PDF_SPEC_DIR 中的 PDF 文件:
| 类别 | 规范 ID | 文档 |
|---|---|---|
| 标准 | iso32000-2、iso32000-2-2020、pdf17、pdf17old | ISO 32000-2(PDF 2.0)、ISO 32000-1(PDF 1.7) |
| 技术规范 | ts32001 – ts32005 | 哈希、数字签名、AES-GCM、完整性、命名空间 |
| PDF/UA | pdfua1、pdfua2 | 无障碍(ISO 14289-1、14289-2) |
| 指南 | tagged-bpg、wtpdf、declarations | Tagged PDF、Well-Tagged PDF、声明 |
| 应用说明 | an001 – an003 | BPC、关联文件、对象元数据 |
目录结构
src/
├── index.ts # Entry point: MCP server on stdio, or the cache CLI
├── cli.ts # --build-cache / --clear-cache / --cache-info
├── config.ts # Configuration & spec patterns
├── errors.ts # Error hierarchy (PDFSpecError → sub-classes)
├── services/
│ ├── pdf-registry.ts # Auto-discovery of PDF files
│ ├── pdf-loader.ts # PDF loading with LRU cache
│ ├── pdf-service.ts # Orchestration layer
│ ├── index-store.ts # On-disk cache for the search / requirements indexes
│ ├── compare-service.ts # Version comparison
│ ├── outline-resolver.ts # Section index builder
│ ├── content-extractor.ts # Structured content extraction
│ ├── search-index.ts # Full-text search index
│ ├── requirement-extractor.ts
│ └── definition-extractor.ts
├── tools/
│ ├── definitions.ts # MCP tool schemas
│ └── handlers.ts # Tool implementations
├── types/
│ └── index.ts # Shared type definitions
└── utils/
├── concurrency.ts # mapConcurrent (bounded Promise.all)
├── text.ts # Text normalization
├── cache.ts # LRU cache
├── file-hash.ts # SHA-256 of a PDF (index cache key)
├── validation.ts # Input validation
└── logger.ts # Structured logger
开发
git clone https://github.com/shuji-bonji/pdf-spec-mcp.git
cd pdf-spec-mcp
npm install
npm run build
# Unit tests
npm run test
# E2E tests (requires PDF files in ./pdf-spec/)
npm run test:e2e
# Lint & format
npm run lint
npm run format:check
许可证
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。