npm - @shuji-bonji/pdf-spec-mcp - Versions diffs - 0.2.1 → 0.2.3 - Mend

@shuji-bonji/pdf-spec-mcp 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.ja.md CHANGED Viewed

@@ -7,6 +7,14 @@
 ISO 32000（PDF）仕様書への構造化アクセスを提供する MCP（Model Context Protocol）サーバーです。LLM が PDF 仕様書をナビゲート・検索・分析するためのツールを提供します。
+> [!IMPORTANT]
+> **PDF 仕様書ファイルは同梱されていません。**
+> このサーバーを利用するには、PDF 仕様書を別途入手し、ローカルディレクトリに配置する必要があります。
+>
+> **入手先:** [PDF Association — Sponsored Standards](https://pdfa.org/sponsored-standards/)
+>
+> 詳しくは「[セットアップ](#セットアップ)」を参照してください。
 ## 特徴
 - **マルチ仕様対応** — 最大17の PDF 関連文書を自動検出（ISO 32000-2、PDF/UA、Tagged PDF ガイド等）
@@ -18,57 +26,161 @@ ISO 32000（PDF）仕様書への構造化アクセスを提供する MCP（Mode
 - **バージョン比較** — PDF 1.7 と PDF 2.0 のセクション構造差分
 - **並行処理** — 大規模ドキュメントのチャンク並行ページ処理
-## 提供ツール
+## アーキテクチャ
-| ツール             | 説明                                            |
-| ------------------ | ----------------------------------------------- |
-| `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 のセクション構造を比較       |
+```mermaid
+graph  LR
+    subgraph Client["MCP クライアント"]
+        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/>PDF 自動検出"]
+            LOADER["Loader<br/>LRU キャッシュ"]
+            SVC["PDFService<br/>オーケストレーション"]
+            CMP["CompareService<br/>バージョン比較"]
+        end
+        subgraph Extractors["Extractors"]
+            direction LR
+            OUTLINE["OutlineResolver<br/>目次・セクション索引"]
+            CONTENT["ContentExtractor<br/>構造化抽出"]
+            SEARCH["SearchIndex<br/>全文検索"]
+            REQ["RequirementExtractor"]
+            DEF["DefinitionExtractor"]
+        end
+        subgraph Utils["Utils"]
+            direction LR
+            CACHE["LRU Cache"]
+            CONC["Concurrency"]
+            VALID["Validation"]
+        end
+    end
+    subgraph PDFs["PDF 仕様書ファイル (別途入手)"]
+        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 等"]
+    end
+    LLM <-->|"stdio / JSON-RPC"| MCP
+    MCP --> Tools
+    Tools --> Services
+    Services --> Extractors
+    Services --> Utils
+    LOADER --> PDFs
+    REG -->|"ファイル名パターン<br/>自動検出"| 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
+```
-## 対応仕様
+### レイヤー構成
-`PDF_SPEC_DIR` 内の PDF ファイルをファイル名パターンで自動検出します：
+| レイヤー       | 役割                                                               |
+| -------------- | ------------------------------------------------------------------ |
+| **Tools**      | MCP ツールスキーマ定義 & ハンドラー（入力バリデーション）          |
+| **Services**   | ビジネスロジック（PDF レジストリ、ローダー、オーケストレーション） |
+| **Extractors** | PDF からの情報抽出（目次、コンテンツ、検索、要件、定義）           |
+| **Utils**      | 共通ユーティリティ（キャッシュ、並行処理、バリデーション）         |
-| カテゴリ                   | Spec 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、Declarations         |
-| **アプリケーションノート** | `an001` – `an003`                                    | BPC、Associated Files、Object Metadata            |
+## セットアップ
+### 1. PDF 仕様書の入手
+> [!WARNING]
+> PDF 仕様書は **著作権で保護されたドキュメント** であり、このパッケージには含まれていません。
+> 以下から入手し、任意のローカルディレクトリに配置してください。
+| 文書                      | 入手先                                                                                          |
+| ------------------------- | ----------------------------------------------------------------------------------------------- |
+| ISO 32000-2 (PDF 2.0)     | [PDF Association](https://pdfa.org/resource/iso-32000-pdf/)                                     |
+| ISO 32000-1 (PDF 1.7)     | [Adobe (無償)](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf) |
+| TS 32001–32005, PDF/UA 等 | [PDF Association — Sponsored Standards](https://pdfa.org/sponsored-standards/)                  |
-## 前提条件
+以下の全17ファイルに対応しています。すべてを揃える必要はなく、必要な仕様書だけ配置すれば動作します（最低限 ISO 32000-2 を推奨）。
-- Node.js >= 20.0.0
-- PDF 仕様書ファイル（同梱されません — [PDF Association](https://pdfa.org/sponsored-standards/) から入手してください）
+```
+pdf-specs/
+│
+│ ── 標準 ──────────────────────────────────
+├── ISO_32000-2_sponsored-ec2.pdf          # iso32000-2  : PDF 2.0 EC2（推奨・主対象）
+├── ISO_32000-2-2020_sponsored.pdf         # iso32000-2-2020 : PDF 2.0 原版
+├── PDF32000_2008.pdf                      # pdf17       : PDF 1.7（バージョン比較用）
+├── pdfreference1.7old.pdf                 # pdf17old    : Adobe PDF Reference 1.7
+│
+│ ── 技術仕様（TS）──────────────────────────
+├── ISO_TS_32001-2022_sponsored.pdf        # ts32001     : ハッシュ拡張 (SHA-3)
+├── ISO_TS_32002-2022_sponsored.pdf        # ts32002     : 電子署名拡張 (ECC/PAdES)
+├── ISO_TS_32003-2023_sponsored.pdf        # ts32003     : AES-GCM 暗号化
+├── ISO-TS-32004-2024_sponsored.pdf        # ts32004     : 整合性保護
+├── ISO-TS-32005-2023-sponsored.pdf        # ts32005     : 名前空間マッピング
+│
+│ ── PDF/UA（アクセシビリティ）──────────────
+├── ISO-14289-1-2014-sponsored.pdf         # pdfua1      : PDF/UA-1
+├── ISO-14289-2-2024-sponsored.pdf         # pdfua2      : PDF/UA-2
+│
+│ ── ガイド ─────────────────────────────────
+├── Tagged-PDF-Best-Practice-Guide.pdf     # tagged-bpg  : Tagged PDF ベストプラクティス
+├── Well-Tagged-PDF-WTPDF-1.0.pdf          # wtpdf       : Well-Tagged PDF
+├── PDF-Declarations.pdf                   # declarations: PDF Declarations
+│
+│ ── アプリケーションノート ─────────────────
+├── PDF20_AN001-BPC.pdf                    # an001       : Black Point Compensation
+├── PDF20_AN002-AF.pdf                     # an002       : Associated Files
+└── PDF20_AN003-ObjectMetadataLocations.pdf # an003      : Object Metadata
+```
+### 2. インストール
+このパッケージは MCP クライアントから起動される CLI バイナリ（`pdf-spec-mcp`）を提供します。
+**通常は手動でインストールする必要はありません** — 次のステップのように MCP クライアント側で `npx @shuji-bonji/pdf-spec-mcp` を指定してください。
-## インストール
+シェルから直接動作確認したい場合（デバッグ用途など）:
 ```bash
-npm install @shuji-bonji/pdf-spec-mcp
+PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp
 ```
-npx での直接実行も可能です：
+グローバルインストールしたい場合（任意）:
 ```bash
-PDF_SPEC_DIR=/path/to/pdf-specs npx @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 クライアント設定
-### 環境変数
+#### 環境変数
 | 変数           | 説明                                       | デフォルト |
 | -------------- | ------------------------------------------ | ---------- |
 | `PDF_SPEC_DIR` | PDF 仕様書ファイルが格納されたディレクトリ | （必須）   |
-### Claude Desktop
+#### Claude Desktop
 `claude_desktop_config.json` に追加：
@@ -86,7 +198,7 @@ PDF_SPEC_DIR=/path/to/pdf-specs npx @shuji-bonji/pdf-spec-mcp
 }
 ```
-### Cursor / VS Code
+#### Cursor / VS Code
 `.cursor/mcp.json` または VS Code の MCP 設定に追加：
@@ -104,22 +216,165 @@ PDF_SPEC_DIR=/path/to/pdf-specs npx @shuji-bonji/pdf-spec-mcp
 }
 ```
-## 使用例
+## 提供ツール
+全ツールで `spec` パラメータにより対象仕様を切り替えられます（デフォルト: `iso32000-2`）。
+> **Note:** 以前検討されていた `get_ts_section` は、`get_section` に `spec` パラメータを追加することで統合されました。
+> TS 仕様や PDF/UA も同じツールセットで参照できます。
+| ツール             | 説明                                            |
+| ------------------ | ----------------------------------------------- |
+| `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` — 仕様一覧
+利用可能な全仕様書の一覧を取得します。他のツールで使う `spec` ID を確認できます。
-接続後、LLM は以下のようにツールを利用できます：
+```jsonc
+// 全仕様を一覧
+{ }
+// カテゴリでフィルタ
+{ "category": "ts" }        // 技術仕様のみ
+{ "category": "pdfua" }     // PDF/UA のみ
+{ "category": "guide" }     // ガイド文書のみ
 ```
-> list_specs
-> get_structure { "max_depth": 2 }
-> get_section { "section": "7.3.4" }
-> search_spec { "query": "digital signature" }
-> get_requirements { "section": "12.8", "level": "shall" }
-> get_definitions { "term": "font" }
-> get_tables { "section": "7.3.4" }
-> compare_versions { "section": "12.8" }
+### `get_structure` — 目次取得
+仕様書のセクション階層（目次ツリー）を取得します。
+```jsonc
+// PDF 2.0 のトップレベルセクションのみ
+{ "max_depth": 1 }
+// 2階層まで展開
+{ "max_depth": 2 }
+// TS 32002（電子署名）の全構造
+{ "spec": "ts32002" }
+// PDF/UA-2 の構造
+{ "spec": "pdfua2", "max_depth": 2 }
 ```
-## アーキテクチャ
+### `get_section` — セクション内容取得
+指定セクションの構造化コンテンツ（見出し・段落・リスト・テーブル・注記）を取得します。
+```jsonc
+// PDF 2.0 のセクション 7.3.4（String Objects）
+{ "section": "7.3.4" }
+// PDF 2.0 の Annex A
+{ "section": "Annex A" }
+// TS 32002 のセクション 5
+{ "spec": "ts32002", "section": "5" }
+// PDF/UA-2 のセクション 8（Tagged PDF）
+{ "spec": "pdfua2", "section": "8" }
+```
+### `search_spec` — 全文検索
+仕様書内をキーワード検索し、セクションコンテキスト付きの結果を返します。
+```jsonc
+// PDF 2.0 で "digital signature" を検索
+{ "query": "digital signature" }
+// 結果数を制限
+{ "query": "font", "max_results": 5 }
+// TS 32002 内で検索
+{ "spec": "ts32002", "query": "CMS" }
+```
+### `get_requirements` — 要件抽出
+ISO 規約に基づく規範的要件（shall / must / may）を抽出します。
+```jsonc
+// セクション 12.8 の全要件
+{ "section": "12.8" }
+// "shall" 要件のみ
+{ "section": "12.8", "level": "shall" }
+// "shall not" 要件のみ
+{ "section": "7.3", "level": "shall not" }
+// PDF/UA-2 の要件
+{ "spec": "pdfua2", "section": "8", "level": "shall" }
+```
+### `get_definitions` — 用語定義検索
+Section 3（用語定義）からの用語検索を行います。
+```jsonc
+// "font" に関する定義を検索
+{ "term": "font" }
+// 全定義を一覧
+{ }
+// PDF/UA の用語定義
+{ "spec": "pdfua2", "term": "artifact" }
+```
+### `get_tables` — テーブル抽出
+セクション内のテーブル構造（ヘッダー・行・キャプション）を抽出します。複数ページにまたがるテーブルも自動マージされます。
+```jsonc
+// セクション 7.3.4 の全テーブル
+{ "section": "7.3.4" }
+// 特定のテーブルのみ（0始まりのインデックス）
+{ "section": "7.3.4", "table_index": 0 }
+// TS 仕様のテーブル
+{ "spec": "ts32002", "section": "5" }
+```
+### `compare_versions` — バージョン比較
+PDF 1.7（ISO 32000-1）と PDF 2.0（ISO 32000-2）のセクション構造を比較します。タイトルベースの自動マッチングにより、一致・追加・削除されたセクションを検出します。
+> [!NOTE]
+> このツールには PDF 1.7 (`PDF32000_2008.pdf`) と PDF 2.0 の両方が `PDF_SPEC_DIR` に必要です。
+```jsonc
+// セクション 12.8（Digital Signatures）の差分
+{ "section": "12.8" }
+// トップレベルの全セクション比較
+{ }
+```
+## 対応仕様
+`PDF_SPEC_DIR` 内の PDF ファイルをファイル名パターンで自動検出します：
+| カテゴリ                   | Spec 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、Declarations         |
+| **アプリケーションノート** | `an001` – `an003`                                    | BPC、Associated Files、Object Metadata            |
+## ディレクトリ構造
 ```
 src/
@@ -140,6 +395,8 @@ src/
 ├── tools/
 │   ├── definitions.ts    # MCP ツールスキーマ
 │   └── handlers.ts       # ツール実装
+├── types/
+│   └── index.ts          # 共有型定義
 └── utils/
     ├── concurrency.ts    # mapConcurrent（制限付き並行 Promise.all）
     ├── text.ts           # テキスト正規化

package/README.md CHANGED Viewed

@@ -7,6 +7,14 @@
 An MCP (Model Context Protocol) server that provides structured access to ISO 32000 (PDF) specification documents. Enables LLMs to navigate, search, and analyze PDF specifications through well-defined tools.
+> [!IMPORTANT]
+> **PDF specification files are NOT included in this package.**
+> You must obtain the PDF specification documents separately and place them in a local directory.
+>
+> **Download from:** [PDF Association — Sponsored Standards](https://pdfa.org/sponsored-standards/)
+>
+> See "[Setup](#setup)" for details.
 ## Features
 - **Multi-spec support** — Auto-discovers and manages up to 17 PDF-related documents (ISO 32000-2, PDF/UA, Tagged PDF guides, etc.)
@@ -18,57 +26,161 @@ An MCP (Model Context Protocol) server that provides structured access to ISO 32
 - **Version comparison** — Diff PDF 1.7 vs PDF 2.0 section structures
 - **Bounded-concurrency processing** — Parallel page processing for large documents
-## Available Tools
+## Architecture
-| Tool               | Description                                                       |
-| ------------------ | ----------------------------------------------------------------- |
-| `list_specs`       | List all discovered PDF specifications with metadata              |
-| `get_structure`    | Get section hierarchy (table of contents) with configurable depth |
-| `get_section`      | Get structured content of a specific section                      |
-| `search_spec`      | Full-text keyword search across a specification                   |
-| `get_requirements` | Extract normative requirements (shall/must/may)                   |
-| `get_definitions`  | Lookup term definitions                                           |
-| `get_tables`       | Extract table structures from a section                           |
-| `compare_versions` | Compare PDF 1.7 and PDF 2.0 section structures                    |
+```mermaid
+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
+```
-## Supported Specifications
+### Layer Overview
-The server auto-discovers PDF files in `PDF_SPEC_DIR` by filename pattern matching:
+| Layer          | Responsibility                                                                     |
+| -------------- | ---------------------------------------------------------------------------------- |
+| **Tools**      | MCP tool schema definitions & handlers (input validation)                          |
+| **Services**   | Business logic (PDF registry, loader, orchestration)                               |
+| **Extractors** | Information extraction from PDFs (TOC, content, search, requirements, definitions) |
+| **Utils**      | Shared utilities (cache, concurrency, validation)                                  |
-| Category           | Spec IDs                                             | Documents                                               |
-| ------------------ | ---------------------------------------------------- | ------------------------------------------------------- |
-| **Standard**       | `iso32000-2`, `iso32000-2-2020`, `pdf17`, `pdf17old` | ISO 32000-2 (PDF 2.0), ISO 32000-1 (PDF 1.7)            |
-| **Technical Spec** | `ts32001` – `ts32005`                                | Hash, Digital Signatures, AES-GCM, Integrity, Namespace |
-| **PDF/UA**         | `pdfua1`, `pdfua2`                                   | Accessibility (ISO 14289-1, 14289-2)                    |
-| **Guide**          | `tagged-bpg`, `wtpdf`, `declarations`                | Tagged PDF, Well-Tagged PDF, Declarations               |
-| **App Note**       | `an001` – `an003`                                    | BPC, Associated Files, Object Metadata                  |
+## Setup
-## Prerequisites
+### 1. Obtain PDF Specification Files
-- Node.js >= 20.0.0
-- PDF specification files (not included — obtain from [PDF Association](https://pdfa.org/sponsored-standards/))
+> [!WARNING]
+> PDF specifications are **copyrighted documents** and are not included in this package.
+> Download them from the sources below and place them in a local directory.
-## Installation
+| Document                     | Source                                                                                          |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- |
+| ISO 32000-2 (PDF 2.0)        | [PDF Association](https://pdfa.org/resource/iso-32000-pdf/)                                     |
+| ISO 32000-1 (PDF 1.7)        | [Adobe (free)](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf) |
+| TS 32001–32005, PDF/UA, etc. | [PDF Association — Sponsored Standards](https://pdfa.org/sponsored-standards/)                  |
+All 17 files below are supported. You do not need all of them — place only the specs you need (at minimum, ISO 32000-2 is recommended).
+```
+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. Install
+This package ships a CLI binary (`pdf-spec-mcp`) intended to be launched by an MCP client.
+**You do not need to install it manually** — just point your MCP client to `npx @shuji-bonji/pdf-spec-mcp` as shown in the next step.
+If you want to run it directly from the shell (e.g. for debugging):
 ```bash
-npm install @shuji-bonji/pdf-spec-mcp
+PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp
 ```
-Or run directly with npx:
+Or install it globally (optional):
 ```bash
-PDF_SPEC_DIR=/path/to/pdf-specs npx @shuji-bonji/pdf-spec-mcp
+npm install -g @shuji-bonji/pdf-spec-mcp
+PDF_SPEC_DIR=/path/to/pdf-specs pdf-spec-mcp
 ```
-## Configuration
+### 3. Configure MCP Client
-### Environment Variable
+#### Environment Variable
 | Variable       | Description                                  | Default    |
 | -------------- | -------------------------------------------- | ---------- |
 | `PDF_SPEC_DIR` | Directory containing PDF specification files | (required) |
-### Claude Desktop
+#### Claude Desktop
 Add to `claude_desktop_config.json`:
@@ -86,7 +198,7 @@ Add to `claude_desktop_config.json`:
 }
 ```
-### Cursor / VS Code
+#### Cursor / VS Code
 Add to `.cursor/mcp.json` or VS Code MCP settings:
@@ -104,22 +216,162 @@ Add to `.cursor/mcp.json` or VS Code MCP settings:
 }
 ```
-## Usage Examples
+## Available Tools
+All tools accept an optional `spec` parameter to target a specific specification (default: `iso32000-2`).
+| Tool               | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `list_specs`       | List all discovered PDF specifications with metadata              |
+| `get_structure`    | Get section hierarchy (table of contents) with configurable depth |
+| `get_section`      | Get structured content of a specific section                      |
+| `search_spec`      | Full-text keyword search across a specification                   |
+| `get_requirements` | Extract normative requirements (shall/must/may)                   |
+| `get_definitions`  | Lookup term definitions                                           |
+| `get_tables`       | Extract table structures from a section                           |
+| `compare_versions` | Compare PDF 1.7 and PDF 2.0 section structures                    |
+### `list_specs` — Discover Specifications
+List all available specification documents. Use the returned IDs as the `spec` parameter in other tools.
+```jsonc
+// List all specs
+{ }
+// Filter by category
+{ "category": "ts" }        // Technical specs only
+{ "category": "pdfua" }     // PDF/UA only
+{ "category": "guide" }     // Guide documents only
+```
+### `get_structure` — Table of Contents
+Get the section hierarchy (TOC tree) of a specification.
+```jsonc
+// 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` — Section Content
+Get structured content (headings, paragraphs, lists, tables, notes) of a specific section.
+```jsonc
+// 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` — Full-text Search
+Search across a specification with section-aware context snippets.
-Once connected, your LLM can use tools like:
+```jsonc
+// 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" }
 ```
-> list_specs
-> get_structure { "max_depth": 2 }
-> get_section { "section": "7.3.4" }
-> search_spec { "query": "digital signature" }
-> get_requirements { "section": "12.8", "level": "shall" }
-> get_definitions { "term": "font" }
-> get_tables { "section": "7.3.4" }
-> compare_versions { "section": "12.8" }
+### `get_requirements` — Normative Requirements
+Extract normative requirements (shall / must / may) per ISO conventions.
+```jsonc
+// 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" }
 ```
-## Architecture
+### `get_definitions` — Term Definitions
+Look up term definitions from Section 3 (Definitions).
+```jsonc
+// Search for "font" definitions
+{ "term": "font" }
+// List all definitions
+{ }
+// PDF/UA definitions
+{ "spec": "pdfua2", "term": "artifact" }
+```
+### `get_tables` — Table Extraction
+Extract table structures (headers, rows, captions) from a section. Multi-page tables are automatically merged.
+```jsonc
+// 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` — Version Comparison
+Compare section structures between PDF 1.7 (ISO 32000-1) and PDF 2.0 (ISO 32000-2). Uses title-based automatic matching to detect matched, added, and removed sections.
+> [!NOTE]
+> This tool requires both PDF 1.7 (`PDF32000_2008.pdf`) and PDF 2.0 files in `PDF_SPEC_DIR`.
+```jsonc
+// Diff section 12.8 (Digital Signatures)
+{ "section": "12.8" }
+// Compare all top-level sections
+{ }
+```
+## Supported Specifications
+The server auto-discovers PDF files in `PDF_SPEC_DIR` by filename pattern matching:
+| Category           | Spec IDs                                             | Documents                                               |
+| ------------------ | ---------------------------------------------------- | ------------------------------------------------------- |
+| **Standard**       | `iso32000-2`, `iso32000-2-2020`, `pdf17`, `pdf17old` | ISO 32000-2 (PDF 2.0), ISO 32000-1 (PDF 1.7)            |
+| **Technical Spec** | `ts32001` – `ts32005`                                | Hash, Digital Signatures, AES-GCM, Integrity, Namespace |
+| **PDF/UA**         | `pdfua1`, `pdfua2`                                   | Accessibility (ISO 14289-1, 14289-2)                    |
+| **Guide**          | `tagged-bpg`, `wtpdf`, `declarations`                | Tagged PDF, Well-Tagged PDF, Declarations               |
+| **App Note**       | `an001` – `an003`                                    | BPC, Associated Files, Object Metadata                  |
+## Directory Structure
 ```
 src/
@@ -140,6 +392,8 @@ src/
 ├── 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

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@shuji-bonji/pdf-spec-mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "MCP server for structured understanding of ISO 32000 (PDF) specifications",
   "keywords": [
     "mcp",