Pdf Spec MCP

PDF SPEC MCP服务器

日语版README在这里

MCP（模型上下文协议）服务器，提供对ISO 32000（PDF）规范文档的结构化访问。使LLM能够通过定义良好的工具导航、搜索和分析PDF规范。

\[！重要\] 此软件包中不包括PDF规范文件。 您必须单独获取PDF规范文档并将其放置在本地目录中。 下载地址： PDF协会——赞助标准 请参阅“设置“了解详情。

特性

• 多规格支持 --自动发现和管理多达17个PDF相关文档（ISO 32000-2、PDF/UA、带标签的PDF指南等）
• 结构化内容提取 --任何章节的标题、段落、列表、表格和注释
• 全文搜索 --使用节感知上下文片段进行关键字搜索
• 需求提取 --根据ISO惯例提取规范性语言（应/必须/可以）
• 定义查找 --第3节（定义）中的术语定义
• 表格提取 --通过头部合并进行多页表检测
• 版本比较 --PDF 1.7与PDF 2.0节结构的差异
• 有界并发处理 --大型文档的并行页面处理

建筑

graph LR
    subgraph Client["MCP Client"]
        LLM["LLM
(Claude, etc.)"]
    end

    subgraph Server["PDF Spec MCP Server"]
        direction TB
        MCP["MCP Server
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
Auto-discovery"]
            LOADER["Loader
LRU Cache"]
            SVC["PDFService
Orchestration"]
            CMP["CompareService
Version Diff"]
        end

        subgraph Extractors["Extractors"]
            direction LR
            OUTLINE["OutlineResolver
TOC & Section Index"]
            CONTENT["ContentExtractor
Structured Extraction"]
            SEARCH["SearchIndex
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
(PDF 2.0)"]
        PDF2["ISO 32000-1
(PDF 1.7)"]
        PDF3["TS 32001–32005
PDF/UA, etc."]
    end

    LLM |"stdio / JSON-RPC"| MCP
    MCP --> Tools
    Tools --> Services
    Services --> Extractors
    Services --> Utils
    LOADER --> PDFs
    REG -->|"Filename pattern
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

层概述

设置

1.获取PDF规格文件

\[！警告\] PDF规格如下 受版权保护的文件 并且不包括在此包中。 从下面的源代码下载它们并将其放置在本地目录中。

支持以下所有17个文件。您不需要所有这些，只需放置您需要的规格（至少建议使用ISO 32000-2）。

pdf-specs/
│
│ ── Standards ─────────────────────────────
├── ISO_32000-2_sponsored-ec2.pdf          # iso32000-2  : PDF 2.0 EC2 (recommended)
├── 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.pdf        # ts32001     : Hash extensions (SHA-3)
├── ISO_TS_32002-2022_sponsored.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 如下一步骤所示。

如果你想直接从shell运行它（例如用于调试）：

PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp

或者全局安装（可选）：

npm install -g @shuji-bonji/pdf-spec-mcp
PDF_SPEC_DIR=/path/to/pdf-specs pdf-spec-mcp

3.配置MCP客户端

环境变量

克劳德桌面版

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-spec": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-spec-mcp"],
      "env": {
        "PDF_SPEC_DIR": "/path/to/pdf-specs"
      }
    }
  }
}

光标/VS代码

添加 .cursor/mcp.json 或VS代码MCP设置：

{
  "mcpServers": {
    "pdf-spec": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-spec-mcp"],
      "env": {
        "PDF_SPEC_DIR": "/path/to/pdf-specs"
      }
    }
  }
}

可用工具

所有工具都接受可选 spec 参数以针对特定规范（默认值： iso32000-2).

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 --目录

获取规范的节层次结构（TOC树）。

// 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 --章节内容

获取特定章节的结构化内容（标题、段落、列表、表格、注释）。

// PDF 2.0 Section 7.3.4 (String Objects)
{ "section": "7.3.4" }

// 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惯例提取规范性要求（应/必须/可以）。

// 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 --术语定义

从第3节（定义）中查找术语定义。

// Search for "font" definitions
{ "term": "font" }

// List all definitions
{ }

// PDF/UA definitions
{ "spec": "pdfua2", "term": "artifact" }

get_tables --表格提取

从节中提取表结构（标题、行、标题）。多页表格会自动合并。

// All tables in section 7.3.4
{ "section": "7.3.4" }

// Specific table only (0-based index)
{ "section": "7.3.4", "table_index": 0 }

// TS spec tables
{ "spec": "ts32002", "section": "5" }

compare_versions --版本比较

比较PDF1.7（ISO32000-1）和PDF2.0（ISO32000-2）之间的截面结构。使用基于标题的自动匹配来检测匹配、添加和删除的部分。

\[！注意\] 此工具需要PDF 1.7(PDF32000_2008.pdf)和PDF 2.0文件 PDF_SPEC_DIR.

// Diff section 12.8 (Digital Signatures)
{ "section": "12.8" }

// Compare all top-level sections
{ }

支持的规格

服务器在以下位置自动发现PDF文件 PDF_SPEC_DIR 通过文件名模式匹配：

目录结构

src/
├── index.ts              # MCP server entry point
├── config.ts             # Configuration & spec patterns
├── errors.ts             # Error hierarchy (PDFSpecError → sub-classes)
├── container.ts          # Service container (DI wiring)
├── services/
│   ├── pdf-registry.ts       # Auto-discovery of PDF files
│   ├── pdf-loader.ts         # PDF loading with LRU cache
│   ├── pdf-service.ts        # Orchestration layer
│   ├── 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
    ├── 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 (237 tests)
npm run test

# E2E tests (212 tests — requires PDF files in ./pdf-spec/)
npm run test:e2e

# Lint & format
npm run lint
npm run format:check

许可证

麻省理工学院