@sylphx/pdf-reader-mcp 1.3.0 โ†’ 1.4.0

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 (11) hide show
  1. package/README.md +205 -91
  2. package/dist/index.js +620 -49
  3. package/package.json +44 -42
  4. package/dist/handlers/index.js +0 -4
  5. package/dist/handlers/readPdf.js +0 -170
  6. package/dist/pdf/extractor.js +0 -394
  7. package/dist/pdf/loader.js +0 -53
  8. package/dist/pdf/parser.js +0 -96
  9. package/dist/schemas/readPdf.js +0 -59
  10. package/dist/types/pdf.js +0 -2
  11. package/dist/utils/pathUtils.js +0 -25
package/README.md CHANGED
@@ -1,19 +1,20 @@
1
1
  <div align="center">
2
2
 
3
- # PDF Reader MCP โšก
3
+ # PDF Reader MCP ๐Ÿ“„
4
4
 
5
- **The fastest and most powerful PDF processing server for AI agents**
5
+ **Production-ready PDF processing server for AI agents**
6
6
 
7
- [![CI/CD](https://github.com/sylphxltd/pdf-reader-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sylphxltd/pdf-reader-mcp/actions/workflows/ci.yml)
8
- [![codecov](https://codecov.io/gh/sylphxltd/pdf-reader-mcp/graph/badge.svg?token=VYRQFB40UN)](https://codecov.io/gh/sylphxltd/pdf-reader-mcp)
9
- [![npm version](https://badge.fury.io/js/%40sylphx%2Fpdf-reader-mcp.svg)](https://www.npmjs.com/package/@sylphx/pdf-reader-mcp)
10
- [![Downloads](https://img.shields.io/npm/dm/@sylphx/pdf-reader-mcp.svg)](https://www.npmjs.com/package/@sylphx/pdf-reader-mcp)
11
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
+ [![CI/CD](https://img.shields.io/github/actions/workflow/status/SylphxAI/pdf-reader-mcp/ci.yml?style=flat-square&label=CI/CD)](https://github.com/SylphxAI/pdf-reader-mcp/actions/workflows/ci.yml)
8
+ [![codecov](https://img.shields.io/codecov/c/github/SylphxAI/pdf-reader-mcp?style=flat-square)](https://codecov.io/gh/SylphxAI/pdf-reader-mcp)
9
+ [![npm version](https://img.shields.io/npm/v/@sylphx/pdf-reader-mcp?style=flat-square)](https://www.npmjs.com/package/@sylphx/pdf-reader-mcp)
10
+ [![coverage](https://img.shields.io/badge/coverage-94.17%25-brightgreen?style=flat-square)](https://pdf-reader-msu3esos4-sylphx.vercel.app)
11
+ [![Downloads](https://img.shields.io/npm/dm/@sylphx/pdf-reader-mcp?style=flat-square)](https://www.npmjs.com/package/@sylphx/pdf-reader-mcp)
12
+ [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](https://opensource.org/licenses/MIT)
12
13
 
13
- **5-10x faster parallel processing** โ€ข **Y-coordinate content ordering** โ€ข **94%+ test coverage** โ€ข **Production-ready**
14
+ **5-10x faster parallel processing** โ€ข **Y-coordinate content ordering** โ€ข **94%+ test coverage** โ€ข **103 tests passing**
14
15
 
15
- <a href="https://mseep.ai/app/sylphxltd-pdf-reader-mcp">
16
- <img src="https://mseep.net/pr/sylphxltd-pdf-reader-mcp-badge.png" alt="Security Validated" width="200"/>
16
+ <a href="https://mseep.ai/app/SylphxAI-pdf-reader-mcp">
17
+ <img src="https://mseep.net/pr/SylphxAI-pdf-reader-mcp-badge.png" alt="Security Validated" width="200"/>
17
18
  </a>
18
19
 
19
20
  </div>
@@ -24,57 +25,131 @@
24
25
 
25
26
  PDF Reader MCP is a **production-ready** Model Context Protocol server that empowers AI agents with **enterprise-grade PDF processing capabilities**. Extract text, images, and metadata with unmatched performance and reliability.
26
27
 
27
- **Stop struggling with PDF extraction. Choose PDF Reader MCP.**
28
+ **The Problem:**
29
+ ```typescript
30
+ // Traditional PDF processing
31
+ - Sequential page processing (slow)
32
+ - No natural content ordering
33
+ - Complex path handling
34
+ - Poor error isolation
35
+ ```
36
+
37
+ **The Solution:**
38
+ ```typescript
39
+ // PDF Reader MCP
40
+ - 5-10x faster parallel processing โšก
41
+ - Y-coordinate based ordering ๐Ÿ“
42
+ - Flexible path support (absolute/relative) ๐ŸŽฏ
43
+ - Per-page error resilience ๐Ÿ›ก๏ธ
44
+ - 94%+ test coverage โœ…
45
+ ```
46
+
47
+ **Result: Production-ready PDF processing that scales.**
48
+
49
+ ---
28
50
 
29
- ## โšก Why PDF Reader MCP?
51
+ ## โšก Key Features
30
52
 
31
- ### **Unmatched Performance**
32
- - ๐Ÿš€ **5-10x faster** than sequential processing with automatic parallelization
33
- - ๐Ÿ”ฅ **Process 50-page PDFs** in seconds with multi-core utilization
34
- - โšก **~12,933 ops/sec** error handling, ~5,575 ops/sec text extraction
35
- - ๐Ÿ’จ **Streaming support** for efficient large file handling
53
+ ### Performance
54
+
55
+ - ๐Ÿš€ **5-10x faster** than sequential with automatic parallelization
56
+ - โšก **12,933 ops/sec** error handling, 5,575 ops/sec text extraction
57
+ - ๐Ÿ’จ **Process 50-page PDFs** in seconds with multi-core utilization
36
58
  - ๐Ÿ“ฆ **Lightweight** with minimal dependencies
37
59
 
38
- ### **Developer Experience**
39
- - ๐ŸŽฏ **Path Flexibility** - Absolute & relative paths, Windows/Unix support (NEW v1.3.0)
40
- - ๐Ÿ–ผ๏ธ **Smart Ordering** - Y-coordinate based content extraction preserves layout
60
+ ### Developer Experience
61
+
62
+ - ๐ŸŽฏ **Path Flexibility** - Absolute & relative paths, Windows/Unix support (v1.3.0)
63
+ - ๐Ÿ–ผ๏ธ **Smart Ordering** - Y-coordinate based content preserves document layout
41
64
  - ๐Ÿ›ก๏ธ **Type Safe** - Full TypeScript with strict mode enabled
42
- - ๐Ÿ“š **Battle-tested** - 103 tests, 94%+ coverage, zero compromises
65
+ - ๐Ÿ“š **Battle-tested** - 103 tests, 94%+ coverage, 98%+ function coverage
43
66
  - ๐ŸŽจ **Simple API** - Single tool handles all operations elegantly
44
67
 
45
68
  ---
46
69
 
70
+ ## ๐Ÿ“Š Performance Benchmarks
71
+
72
+ Real-world performance from production testing:
73
+
74
+ | Operation | Ops/sec | Performance | Use Case |
75
+ |-----------|---------|-------------|----------|
76
+ | **Error handling** | 12,933 | โšกโšกโšกโšกโšก | Validation & safety |
77
+ | **Extract full text** | 5,575 | โšกโšกโšกโšก | Document analysis |
78
+ | **Extract page** | 5,329 | โšกโšกโšกโšก | Single page ops |
79
+ | **Multiple pages** | 5,242 | โšกโšกโšกโšก | Batch processing |
80
+ | **Metadata only** | 4,912 | โšกโšกโšก | Quick inspection |
81
+
82
+ ### Parallel Processing Speedup
83
+
84
+ | Document | Sequential | Parallel | Speedup |
85
+ |----------|-----------|----------|---------|
86
+ | **10-page PDF** | ~2s | ~0.3s | **5-8x faster** |
87
+ | **50-page PDF** | ~10s | ~1s | **10x faster** |
88
+ | **100+ pages** | ~20s | ~2s | **Linear scaling** with CPU cores |
89
+
90
+ *Benchmarks vary based on PDF complexity and system resources.*
91
+
92
+ ---
93
+
47
94
  ## ๐Ÿ“ฆ Installation
48
95
 
96
+ ### VS Code
97
+
98
+ Install with one click using the VS Code extension buttons:
99
+
100
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-007ACC?style=for-the-badge&logo=visual-studio-code)](https://insiders.vscode.dev/redirect?url=vscode://ms-vscode.vscode-mcp/install?mcpId=sylphx-pdf-reader-mcp)
101
+ [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=for-the-badge&logo=visual-studio-code)](https://insiders.vscode.dev/redirect?url=vscode-insiders://ms-vscode.vscode-mcp/install?mcpId=sylphx-pdf-reader-mcp)
102
+
103
+ Or via CLI:
104
+
49
105
  ```bash
50
- # Quick start - zero installation
51
- npx @sylphx/pdf-reader-mcp
106
+ code --add-mcp '{"name":"pdf-reader","command":"npx","args":["@sylphx/pdf-reader-mcp"]}'
107
+ ```
52
108
 
53
- # Using pnpm (recommended)
54
- pnpm add @sylphx/pdf-reader-mcp
109
+ ### Claude Code
55
110
 
56
- # Using npm
57
- npm install @sylphx/pdf-reader-mcp
111
+ ```bash
112
+ claude mcp add pdf-reader -- npx @sylphx/pdf-reader-mcp
113
+ ```
58
114
 
59
- # Using yarn
60
- yarn add @sylphx/pdf-reader-mcp
115
+ ### Claude Desktop
61
116
 
62
- # For Claude Desktop (easiest)
63
- npx -y @smithery/cli install @sylphx/pdf-reader-mcp --client claude
117
+ Add to `claude_desktop_config.json`:
118
+
119
+ ```json
120
+ {
121
+ "mcpServers": {
122
+ "pdf-reader": {
123
+ "command": "npx",
124
+ "args": ["@sylphx/pdf-reader-mcp"]
125
+ }
126
+ }
127
+ }
64
128
  ```
65
129
 
66
- ---
130
+ <details>
131
+ <summary><strong>๐Ÿ“ Config file locations</strong></summary>
67
132
 
68
- ## ๐ŸŽฏ Quick Start
133
+ - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
134
+ - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
135
+ - **Linux**: `~/.config/Claude/claude_desktop_config.json`
69
136
 
70
- ### Configuration
137
+ </details>
138
+
139
+ ### Cursor
140
+
141
+ 1. Open **Settings** โ†’ **MCP** โ†’ **Add new MCP Server**
142
+ 2. Select **Command** type
143
+ 3. Enter: `npx @sylphx/pdf-reader-mcp`
144
+
145
+ ### Windsurf
71
146
 
72
- Add to your MCP client (`claude_desktop_config.json`, Cursor, Cline):
147
+ Add to your Windsurf MCP config:
73
148
 
74
149
  ```json
75
150
  {
76
151
  "mcpServers": {
77
- "pdf-reader-mcp": {
152
+ "pdf-reader": {
78
153
  "command": "npx",
79
154
  "args": ["@sylphx/pdf-reader-mcp"]
80
155
  }
@@ -82,6 +157,49 @@ Add to your MCP client (`claude_desktop_config.json`, Cursor, Cline):
82
157
  }
83
158
  ```
84
159
 
160
+ ### Cline
161
+
162
+ Add to Cline's MCP settings:
163
+
164
+ ```json
165
+ {
166
+ "mcpServers": {
167
+ "pdf-reader": {
168
+ "command": "npx",
169
+ "args": ["@sylphx/pdf-reader-mcp"]
170
+ }
171
+ }
172
+ }
173
+ ```
174
+
175
+ ### Warp
176
+
177
+ 1. Go to **Settings** โ†’ **AI** โ†’ **Manage MCP Servers** โ†’ **Add**
178
+ 2. Or use the `/add-mcp` slash command with the standard config
179
+
180
+ ### Smithery (One-click)
181
+
182
+ ```bash
183
+ npx -y @smithery/cli install @sylphx/pdf-reader-mcp --client claude
184
+ ```
185
+
186
+ ### Manual Installation
187
+
188
+ ```bash
189
+ # Quick start - zero installation
190
+ npx @sylphx/pdf-reader-mcp
191
+
192
+ # Using bun (recommended)
193
+ bun add @sylphx/pdf-reader-mcp
194
+
195
+ # Using npm
196
+ npm install @sylphx/pdf-reader-mcp
197
+ ```
198
+
199
+ ---
200
+
201
+ ## ๐ŸŽฏ Quick Start
202
+
85
203
  ### Basic Usage
86
204
 
87
205
  ```json
@@ -113,7 +231,7 @@ Add to your MCP client (`claude_desktop_config.json`, Cursor, Cline):
113
231
  }
114
232
  ```
115
233
 
116
- ### Absolute Paths (NEW in v1.3.0!)
234
+ ### Absolute Paths (v1.3.0+)
117
235
 
118
236
  ```json
119
237
  // Windows - Both formats work!
@@ -484,30 +602,6 @@ Restart MCP client completely.
484
602
 
485
603
  ---
486
604
 
487
- ## โšก Performance
488
-
489
- ### Benchmarks
490
-
491
- | Operation | Ops/sec | Performance |
492
- |:----------|:--------|:------------|
493
- | Error handling | ~12,933 | โšกโšกโšกโšกโšก |
494
- | Extract full text | ~5,575 | โšกโšกโšกโšก |
495
- | Extract page | ~5,329 | โšกโšกโšกโšก |
496
- | Multiple pages | ~5,242 | โšกโšกโšกโšก |
497
- | Metadata only | ~4,912 | โšกโšกโšก |
498
-
499
- ### Parallel Processing
500
-
501
- | Document | Speedup |
502
- |:---------|:--------|
503
- | 10-page PDF | **5-8x faster** |
504
- | 50-page PDF | **10x faster** |
505
- | 100+ pages | **Linear scaling** with CPU cores |
506
-
507
- *Benchmarks vary based on PDF complexity and system resources.*
508
-
509
- ---
510
-
511
605
  ## ๐Ÿ—๏ธ Architecture
512
606
 
513
607
  ### Tech Stack
@@ -548,7 +642,7 @@ Restart MCP client completely.
548
642
 
549
643
  **Setup:**
550
644
  ```bash
551
- git clone https://github.com/sylphxltd/pdf-reader-mcp.git
645
+ git clone https://github.com/SylphxAI/pdf-reader-mcp.git
552
646
  cd pdf-reader-mcp
553
647
  pnpm install && pnpm build
554
648
  ```
@@ -600,7 +694,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md)
600
694
 
601
695
  ## ๐Ÿ“š Documentation
602
696
 
603
- - ๐Ÿ“– [Full Docs](https://sylphxltd.github.io/pdf-reader-mcp/) - Complete guides
697
+ - ๐Ÿ“– [Full Docs](https://SylphxAI.github.io/pdf-reader-mcp/) - Complete guides
604
698
  - ๐Ÿš€ [Getting Started](./docs/guide/getting-started.md) - Quick start
605
699
  - ๐Ÿ“˜ [API Reference](./docs/api/README.md) - Detailed API
606
700
  - ๐Ÿ—๏ธ [Design](./docs/design/index.md) - Architecture
@@ -618,7 +712,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md)
618
712
  - [x] Absolute paths (v1.3.0)
619
713
  - [x] 94%+ test coverage (v1.3.0)
620
714
 
621
- **๐Ÿš€ Coming Soon**
715
+ **๐Ÿš€ Next**
622
716
  - [ ] OCR for scanned PDFs
623
717
  - [ ] Annotation extraction
624
718
  - [ ] Form field extraction
@@ -627,19 +721,30 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md)
627
721
  - [ ] Advanced caching
628
722
  - [ ] PDF generation
629
723
 
630
- Vote at [Discussions](https://github.com/sylphxltd/pdf-reader-mcp/discussions)
724
+ Vote at [Discussions](https://github.com/SylphxAI/pdf-reader-mcp/discussions)
725
+
726
+ ---
727
+
728
+ ## ๐Ÿ† Recognition
729
+
730
+ **Featured on:**
731
+ - [Smithery](https://smithery.ai/server/@sylphx/pdf-reader-mcp) - MCP directory
732
+ - [Glama](https://glama.ai/mcp/servers/@sylphx/pdf-reader-mcp) - AI marketplace
733
+ - [MseeP.ai](https://mseep.ai/app/SylphxAI-pdf-reader-mcp) - Security validated
734
+
735
+ **Trusted worldwide** โ€ข **Enterprise adoption** โ€ข **Battle-tested**
631
736
 
632
737
  ---
633
738
 
634
739
  ## ๐Ÿค Support
635
740
 
636
- [![Issues](https://img.shields.io/github/issues/sylphxltd/pdf-reader-mcp?style=for-the-badge&logo=github)](https://github.com/sylphxltd/pdf-reader-mcp/issues)
637
- [![Discussions](https://img.shields.io/github/discussions/sylphxltd/pdf-reader-mcp?style=for-the-badge&logo=github)](https://github.com/sylphxltd/pdf-reader-mcp/discussions)
741
+ [![GitHub Issues](https://img.shields.io/github/issues/SylphxAI/pdf-reader-mcp?style=flat-square)](https://github.com/SylphxAI/pdf-reader-mcp/issues)
742
+ [![Discord](https://img.shields.io/discord/YOUR_DISCORD_ID?style=flat-square&logo=discord)](https://discord.gg/sylphx)
638
743
 
639
- - ๐Ÿ› [Bug Reports](https://github.com/sylphxltd/pdf-reader-mcp/issues)
640
- - ๐Ÿ’ฌ [Discussions](https://github.com/sylphxltd/pdf-reader-mcp/discussions)
641
- - ๐Ÿ“– [Contributing](./CONTRIBUTING.md)
642
- - ๐Ÿ“ง contact@sylphx.com
744
+ - ๐Ÿ› [Bug Reports](https://github.com/SylphxAI/pdf-reader-mcp/issues)
745
+ - ๐Ÿ’ฌ [Discussions](https://github.com/SylphxAI/pdf-reader-mcp/discussions)
746
+ - ๐Ÿ“– [Documentation](https://SylphxAI.github.io/pdf-reader-mcp/)
747
+ - ๐Ÿ“ง [Email](mailto:hi@sylphx.com)
643
748
 
644
749
  **Show Your Support:**
645
750
  โญ Star โ€ข ๐Ÿ‘€ Watch โ€ข ๐Ÿ› Report bugs โ€ข ๐Ÿ’ก Suggest features โ€ข ๐Ÿ”€ Contribute
@@ -648,40 +753,49 @@ Vote at [Discussions](https://github.com/sylphxltd/pdf-reader-mcp/discussions)
648
753
 
649
754
  ## ๐Ÿ“Š Stats
650
755
 
651
- ![Stars](https://img.shields.io/github/stars/sylphxltd/pdf-reader-mcp?style=social)
652
- ![Forks](https://img.shields.io/github/forks/sylphxltd/pdf-reader-mcp?style=social)
756
+ ![Stars](https://img.shields.io/github/stars/SylphxAI/pdf-reader-mcp?style=social)
757
+ ![Forks](https://img.shields.io/github/forks/SylphxAI/pdf-reader-mcp?style=social)
653
758
  ![Downloads](https://img.shields.io/npm/dm/@sylphx/pdf-reader-mcp)
654
- ![Contributors](https://img.shields.io/github/contributors/sylphxltd/pdf-reader-mcp)
759
+ ![Contributors](https://img.shields.io/github/contributors/SylphxAI/pdf-reader-mcp)
655
760
 
656
761
  **103 Tests** โ€ข **94%+ Coverage** โ€ข **Production Ready**
657
762
 
658
763
  ---
659
764
 
660
- ## ๐Ÿ† Recognition
661
-
662
- **Featured on:**
663
- - [Smithery](https://smithery.ai/server/@sylphx/pdf-reader-mcp) - MCP directory
664
- - [Glama](https://glama.ai/mcp/servers/@sylphx/pdf-reader-mcp) - AI marketplace
665
- - [MseeP.ai](https://mseep.ai/app/sylphxltd-pdf-reader-mcp) - Security validated
765
+ ## ๐Ÿ“„ License
666
766
 
667
- **Trusted worldwide** โ€ข **Enterprise adoption** โ€ข **Battle-tested**
767
+ MIT ยฉ [Sylphx](https://sylphx.com)
668
768
 
669
769
  ---
670
770
 
671
- ## ๐Ÿ“„ License
771
+ ## ๐Ÿ™ Credits
672
772
 
673
- MIT License - Free for personal and commercial use.
773
+ Built with:
774
+ - [PDF.js](https://mozilla.github.io/pdf.js/) - Mozilla PDF engine
775
+ - [Bun](https://bun.sh) - Fast JavaScript runtime
674
776
 
675
- See [LICENSE](./LICENSE) for details.
777
+ Special thanks to the open source community โค๏ธ
676
778
 
677
- ---
779
+ ## Powered by Sylphx
678
780
 
679
- <div align="center">
781
+ This project uses the following [@sylphx](https://github.com/SylphxAI) packages:
680
782
 
681
- **Built with โค๏ธ by [Sylphx](https://sylphx.com)**
783
+ - [@sylphx/mcp-server-sdk](https://github.com/SylphxAI/mcp-server-sdk) - MCP server framework
784
+ - [@sylphx/biome-config](https://github.com/SylphxAI/biome-config) - Biome configuration
785
+ - [@sylphx/tsconfig](https://github.com/SylphxAI/tsconfig) - TypeScript configuration
786
+ - [@sylphx/bump](https://github.com/SylphxAI/bump) - Version management
787
+ - [@sylphx/doctor](https://github.com/SylphxAI/doctor) - Project health checker
788
+ - [@sylphx/leaf](https://github.com/SylphxAI/leaf) - Documentation framework
789
+ - [@sylphx/leaf-theme-default](https://github.com/SylphxAI/leaf-theme-default) - Documentation theme
682
790
 
683
- *Building the future of AI-powered document processing*
684
-
685
- [โฌ† Back to Top](#pdf-reader-mcp-)
791
+ ---
686
792
 
687
- </div>
793
+ <p align="center">
794
+ <strong>5-10x faster. Production-ready. Battle-tested.</strong>
795
+ <br>
796
+ <sub>The PDF processing server that actually scales</sub>
797
+ <br><br>
798
+ <a href="https://sylphx.com">sylphx.com</a> โ€ข
799
+ <a href="https://x.com/SylphxAI">@SylphxAI</a> โ€ข
800
+ <a href="mailto:hi@sylphx.com">hi@sylphx.com</a>
801
+ </p>