mcpField
P
PDF SPEC MCP Server

PDF SPEC MCP Server

本地服务
shuji-bonji.github.io文件与存储24 天前更新

关于 PDF SPEC MCP Server

PDF SPEC MCP Server 为 LLM 提供对 ISO 32000 等 PDF 相关规范的结构化访问,适用于需要搜索条款、提取要求或比较 PDF 版本的开发者和标准研究者。它检索规范文本,但不检查或验证 PDF 文件。

主要功能

  1. 01发现支持的规范文档
  2. 02浏览章节结构和内容
  3. 03搜索规范全文
  4. 04提取规范性要求和定义
  5. 05提取表格并比较 PDF 版本
  6. 06在磁盘缓存搜索索引

适用场景

  1. 01查找 PDF 标准中的条款
  2. 02核对规范性要求的措辞
  3. 03查询规范术语的定义
  4. 04比较 PDF 1.7 与 PDF 2.0 的结构

MCP 相关

向 MCP 客户端提供规范发现、浏览、搜索、提取和比较工具。用户需在本地提供规范 PDF 文件;服务端不会检查 PDF 是否符合规范。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"pdf-spec": {
"command": "npx",
"args": [
"-y",
"@shuji-bonji/pdf-spec-mcp"
]
}
}
}
启动命令npx -y @shuji-bonji/pdf-spec-mcp

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
npm@shuji-bonji/pdf-spec-mcp0.10.0

工具

8

收录的工具列表 · 更新于 2 周前

参数类型必填说明
categorystring否按类别筛选(standard、ts、pdfua、guide、appnote)。

详细介绍

PDF SPEC MCP 服务

CI npm version

日文版 README 请点击此处

这是一个 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、pdf17oldISO 32000-2(PDF 2.0)、ISO 32000-1(PDF 1.7)
技术规范ts32001 – ts32005哈希、数字签名、AES-GCM、完整性、命名空间
PDF/UApdfua1、pdfua2无障碍(ISO 14289-1、14289-2)
指南tagged-bpg、wtpdf、declarationsTagged PDF、Well-Tagged PDF、声明
应用说明an001 – an003BPC、关联文件、对象元数据

目录结构

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

许可证

MIT

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。