[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-SylphxAI--pdf-reader-mcp":3,"tool-SylphxAI--pdf-reader-mcp":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",149489,2,"2026-04-10T11:32:46",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":77,"owner_twitter":76,"owner_website":78,"owner_url":79,"languages":80,"stars":89,"forks":90,"last_commit_at":91,"license":92,"difficulty_score":32,"env_os":93,"env_gpu":94,"env_ram":94,"env_deps":95,"category_tags":100,"github_topics":101,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":118,"updated_at":119,"faqs":120,"releases":150},6305,"SylphxAI\u002Fpdf-reader-mcp","pdf-reader-mcp","📄 Production-ready MCP server for PDF processing - 5-10x faster with parallel processing and 94%+ test coverage","pdf-reader-mcp 是一款专为 AI 智能体打造的生产级 PDF 处理服务器，基于模型上下文协议（MCP）构建。它旨在解决传统 PDF 解析工具处理速度慢、内容顺序混乱以及错误容错性差等痛点。通过引入自动并行处理技术，pdf-reader-mcp 能够利用多核 CPU 同时解析多个页面，将处理效率提升了 5 到 10 倍，即使是百页文档也能在秒级内完成提取。\n\n该工具特别适合开发者、AI 工程师及需要高效处理大量文档的研究人员使用。其核心技术亮点在于独特的\"Y 轴坐标排序”算法，能智能还原文档的自然阅读顺序，避免文本错乱；同时具备强大的错误隔离机制，单页解析失败不会影响整体任务。此外，pdf-reader-mcp 拥有超过 94% 的测试覆盖率，支持 TypeScript 严格模式，并提供灵活的路径处理能力，确保在复杂生产环境中的稳定运行。无论是进行文档分析、批量数据提取还是构建知识库，它都能提供轻量、快速且可靠的解决方案。","\u003Cdiv align=\"center\">\n\n# 📄 @sylphx\u002Fpdf-reader-mcp\n\n> Production-ready PDF processing server for AI agents\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@sylphx\u002Fpdf-reader-mcp?style=flat-square)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@sylphx\u002Fpdf-reader-mcp)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue?style=flat-square)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![CI\u002FCD](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fci.yml?style=flat-square&label=CI\u002FCD)](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Factions\u002Fworkflows\u002Fci.yml)\n[![codecov](https:\u002F\u002Fimg.shields.io\u002Fcodecov\u002Fc\u002Fgithub\u002FSylphxAI\u002Fpdf-reader-mcp?style=flat-square)](https:\u002F\u002Fcodecov.io\u002Fgh\u002FSylphxAI\u002Fpdf-reader-mcp)\n[![coverage](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcoverage-94.17%25-brightgreen?style=flat-square)](https:\u002F\u002Fpdf-reader-msu3esos4-sylphx.vercel.app)\n[![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-5.0-blue.svg?style=flat-square)](https:\u002F\u002Fwww.typescriptlang.org\u002F)\n[![Downloads](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdm\u002F@sylphx\u002Fpdf-reader-mcp?style=flat-square)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@sylphx\u002Fpdf-reader-mcp)\n\n**5-10x faster parallel processing** • **Y-coordinate content ordering** • **94%+ test coverage** • **103 tests passing**\n\n\u003Ca href=\"https:\u002F\u002Fmseep.ai\u002Fapp\u002FSylphxAI-pdf-reader-mcp\">\n\u003Cimg src=\"https:\u002F\u002Fmseep.net\u002Fpr\u002FSylphxAI-pdf-reader-mcp-badge.png\" alt=\"Security Validated\" width=\"200\"\u002F>\n\u003C\u002Fa>\n\n\u003C\u002Fdiv>\n\n---\n\n## 🚀 Overview\n\nPDF 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.\n\n**The Problem:**\n```typescript\n\u002F\u002F Traditional PDF processing\n- Sequential page processing (slow)\n- No natural content ordering\n- Complex path handling\n- Poor error isolation\n```\n\n**The Solution:**\n```typescript\n\u002F\u002F PDF Reader MCP\n- 5-10x faster parallel processing ⚡\n- Y-coordinate based ordering 📐\n- Flexible path support (absolute\u002Frelative) 🎯\n- Per-page error resilience 🛡️\n- 94%+ test coverage ✅\n```\n\n**Result: Production-ready PDF processing that scales.**\n\n---\n\n## ⚡ Key Features\n\n### Performance\n\n- 🚀 **5-10x faster** than sequential with automatic parallelization\n- ⚡ **12,933 ops\u002Fsec** error handling, 5,575 ops\u002Fsec text extraction\n- 💨 **Process 50-page PDFs** in seconds with multi-core utilization\n- 📦 **Lightweight** with minimal dependencies\n\n### Developer Experience\n\n- 🎯 **Path Flexibility** - Absolute & relative paths, Windows\u002FUnix support (v1.3.0)\n- 🖼️ **Smart Ordering** - Y-coordinate based content preserves document layout\n- 🛡️ **Type Safe** - Full TypeScript with strict mode enabled\n- 📚 **Battle-tested** - 103 tests, 94%+ coverage, 98%+ function coverage\n- 🎨 **Simple API** - Single tool handles all operations elegantly\n\n---\n\n## 📊 Performance Benchmarks\n\nReal-world performance from production testing:\n\n| Operation | Ops\u002Fsec | Performance | Use Case |\n|-----------|---------|-------------|----------|\n| **Error handling** | 12,933 | ⚡⚡⚡⚡⚡ | Validation & safety |\n| **Extract full text** | 5,575 | ⚡⚡⚡⚡ | Document analysis |\n| **Extract page** | 5,329 | ⚡⚡⚡⚡ | Single page ops |\n| **Multiple pages** | 5,242 | ⚡⚡⚡⚡ | Batch processing |\n| **Metadata only** | 4,912 | ⚡⚡⚡ | Quick inspection |\n\n### Parallel Processing Speedup\n\n| Document | Sequential | Parallel | Speedup |\n|----------|-----------|----------|---------|\n| **10-page PDF** | ~2s | ~0.3s | **5-8x faster** |\n| **50-page PDF** | ~10s | ~1s | **10x faster** |\n| **100+ pages** | ~20s | ~2s | **Linear scaling** with CPU cores |\n\n*Benchmarks vary based on PDF complexity and system resources.*\n\n---\n\n## 📦 Installation\n\n### Claude Code\n\n```bash\nclaude mcp add pdf-reader -- npx @sylphx\u002Fpdf-reader-mcp\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-reader\": {\n      \"command\": \"npx\",\n      \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"]\n    }\n  }\n}\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📍 Config file locations\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n- **macOS**: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~\u002F.config\u002FClaude\u002Fclaude_desktop_config.json`\n\n\u003C\u002Fdetails>\n\n### VS Code\n\n```bash\ncode --add-mcp '{\"name\":\"pdf-reader\",\"command\":\"npx\",\"args\":[\"@sylphx\u002Fpdf-reader-mcp\"]}'\n```\n\n### Cursor\n\n1. Open **Settings** → **MCP** → **Add new MCP Server**\n2. Select **Command** type\n3. Enter: `npx @sylphx\u002Fpdf-reader-mcp`\n\n### Windsurf\n\nAdd to your Windsurf MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-reader\": {\n      \"command\": \"npx\",\n      \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"]\n    }\n  }\n}\n```\n\n### Cline\n\nAdd to Cline's MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-reader\": {\n      \"command\": \"npx\",\n      \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"]\n    }\n  }\n}\n```\n\n### Warp\n\n1. Go to **Settings** → **AI** → **Manage MCP Servers** → **Add**\n2. Command: `npx`, Args: `@sylphx\u002Fpdf-reader-mcp`\n\n### Smithery (One-click)\n\n```bash\nnpx -y @smithery\u002Fcli install @sylphx\u002Fpdf-reader-mcp --client claude\n```\n\n### Manual Installation\n\n```bash\n# Quick start - zero installation\nnpx @sylphx\u002Fpdf-reader-mcp\n\n# Or install globally\nnpm install -g @sylphx\u002Fpdf-reader-mcp\n```\n\n---\n\n## 🎯 Quick Start\n\n### Basic Usage\n\n```json\n{\n  \"sources\": [{\n    \"path\": \"documents\u002Freport.pdf\"\n  }],\n  \"include_full_text\": true,\n  \"include_metadata\": true,\n  \"include_page_count\": true\n}\n```\n\n**Result:**\n- ✅ Full text content extracted\n- ✅ PDF metadata (author, title, dates)\n- ✅ Total page count\n- ✅ Structural sharing - unchanged parts preserved\n\n### Extract Specific Pages\n\n```json\n{\n  \"sources\": [{\n    \"path\": \"documents\u002Fmanual.pdf\",\n    \"pages\": \"1-5,10,15-20\"\n  }],\n  \"include_full_text\": true\n}\n```\n\n### Absolute Paths (v1.3.0+)\n\n```json\n\u002F\u002F Windows - Both formats work!\n{\n  \"sources\": [{\n    \"path\": \"C:\\\\Users\\\\John\\\\Documents\\\\report.pdf\"\n  }],\n  \"include_full_text\": true\n}\n\n\u002F\u002F Unix\u002FMac\n{\n  \"sources\": [{\n    \"path\": \"\u002Fhome\u002Fuser\u002Fdocuments\u002Fcontract.pdf\"\n  }],\n  \"include_full_text\": true\n}\n```\n\n**No more** `\"Absolute paths are not allowed\"` **errors!**\n\n### Extract Images with Natural Ordering\n\n```json\n{\n  \"sources\": [{\n    \"path\": \"presentation.pdf\",\n    \"pages\": [1, 2, 3]\n  }],\n  \"include_images\": true,\n  \"include_full_text\": true\n}\n```\n\n**Response includes:**\n- Text and images in **exact document order** (Y-coordinate sorted)\n- Base64-encoded images with metadata (width, height, format)\n- Natural reading flow preserved for AI comprehension\n\n### Batch Processing\n\n```json\n{\n  \"sources\": [\n    { \"path\": \"C:\\\\Reports\\\\Q1.pdf\", \"pages\": \"1-10\" },\n    { \"path\": \"\u002Fhome\u002Fuser\u002FQ2.pdf\", \"pages\": \"1-10\" },\n    { \"url\": \"https:\u002F\u002Fexample.com\u002FQ3.pdf\" }\n  ],\n  \"include_full_text\": true\n}\n```\n\n⚡ **All PDFs processed in parallel automatically!**\n\n---\n\n## ✨ Features\n\n### Core Capabilities\n- ✅ **Text Extraction** - Full document or specific pages with intelligent parsing\n- ✅ **Image Extraction** - Base64-encoded with complete metadata (width, height, format)\n- ✅ **Content Ordering** - Y-coordinate based layout preservation for natural reading flow\n- ✅ **Metadata Extraction** - Author, title, creation date, and custom properties\n- ✅ **Page Counting** - Fast enumeration without loading full content\n- ✅ **Dual Sources** - Local files (absolute or relative paths) and HTTP\u002FHTTPS URLs\n- ✅ **Batch Processing** - Multiple PDFs processed concurrently\n\n### Advanced Features\n- ⚡ **5-10x Performance** - Parallel page processing with Promise.all\n- 🎯 **Smart Pagination** - Extract ranges like \"1-5,10-15,20\"\n- 🖼️ **Multi-Format Images** - RGB, RGBA, Grayscale with automatic detection\n- 🛡️ **Path Flexibility** - Windows, Unix, and relative paths all supported (v1.3.0)\n- 🔍 **Error Resilience** - Per-page error isolation with detailed messages\n- 📏 **Large File Support** - Efficient streaming and memory management\n- 📝 **Type Safe** - Full TypeScript with strict mode enabled\n\n---\n\n## 🆕 What's New in v1.3.0\n\n### 🎉 Absolute Paths Now Supported!\n\n```json\n\u002F\u002F ✅ Windows\n{ \"path\": \"C:\\\\Users\\\\John\\\\Documents\\\\report.pdf\" }\n{ \"path\": \"C:\u002FUsers\u002FJohn\u002FDocuments\u002Freport.pdf\" }\n\n\u002F\u002F ✅ Unix\u002FMac\n{ \"path\": \"\u002Fhome\u002Fjohn\u002Fdocuments\u002Freport.pdf\" }\n{ \"path\": \"\u002FUsers\u002Fjohn\u002FDocuments\u002Freport.pdf\" }\n\n\u002F\u002F ✅ Relative (still works)\n{ \"path\": \"documents\u002Freport.pdf\" }\n```\n\n**Other Improvements:**\n- 🐛 Fixed Zod validation error handling\n- 📦 Updated all dependencies to latest versions\n- ✅ 103 tests passing, 94%+ coverage maintained\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📋 View Full Changelog\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**v1.2.0 - Content Ordering**\n- Y-coordinate based text and image ordering\n- Natural reading flow for AI models\n- Intelligent line grouping\n\n**v1.1.0 - Image Extraction & Performance**\n- Base64-encoded image extraction\n- 10x speedup with parallel processing\n- Comprehensive test coverage (94%+)\n\n[View Full Changelog →](.\u002FCHANGELOG.md)\n\n\u003C\u002Fdetails>\n\n---\n\n## 📖 API Reference\n\n### `read_pdf` Tool\n\nThe single tool that handles all PDF operations.\n\n#### Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|---------|\n| `sources` | Array | List of PDF sources to process | Required |\n| `include_full_text` | boolean | Extract full text content | `false` |\n| `include_metadata` | boolean | Extract PDF metadata | `true` |\n| `include_page_count` | boolean | Include total page count | `true` |\n| `include_images` | boolean | Extract embedded images | `false` |\n\n#### Source Object\n\n```typescript\n{\n  path?: string;        \u002F\u002F Local file path (absolute or relative)\n  url?: string;         \u002F\u002F HTTP\u002FHTTPS URL to PDF\n  pages?: string | number[];  \u002F\u002F Pages to extract: \"1-5,10\" or [1,2,3]\n}\n```\n\n#### Examples\n\n**Metadata only (fast):**\n```json\n{\n  \"sources\": [{ \"path\": \"large.pdf\" }],\n  \"include_metadata\": true,\n  \"include_page_count\": true,\n  \"include_full_text\": false\n}\n```\n\n**From URL:**\n```json\n{\n  \"sources\": [{\n    \"url\": \"https:\u002F\u002Farxiv.org\u002Fpdf\u002F2301.00001.pdf\"\n  }],\n  \"include_full_text\": true\n}\n```\n\n**Page ranges:**\n```json\n{\n  \"sources\": [{\n    \"path\": \"manual.pdf\",\n    \"pages\": \"1-5,10-15,20\"  \u002F\u002F Pages 1,2,3,4,5,10,11,12,13,14,15,20\n  }]\n}\n```\n\n---\n\n## 🔧 Advanced Usage\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📐 Y-Coordinate Content Ordering\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\nContent is returned in natural reading order based on Y-coordinates:\n\n```\nDocument Layout:\n┌─────────────────────┐\n│ [Title]       Y:100 │\n│ [Image]       Y:150 │\n│ [Text]        Y:400 │\n│ [Photo A]     Y:500 │\n│ [Photo B]     Y:550 │\n└─────────────────────┘\n\nResponse Order:\n[\n  { type: \"text\", text: \"Title...\" },\n  { type: \"image\", data: \"...\" },\n  { type: \"text\", text: \"...\" },\n  { type: \"image\", data: \"...\" },\n  { type: \"image\", data: \"...\" }\n]\n```\n\n**Benefits:**\n- AI understands spatial relationships\n- Natural document comprehension\n- Perfect for vision-enabled models\n- Automatic multi-line text grouping\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🖼️ Image Extraction\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**Enable extraction:**\n```json\n{\n  \"sources\": [{ \"path\": \"manual.pdf\" }],\n  \"include_images\": true\n}\n```\n\n**Response format:**\n```json\n{\n  \"images\": [{\n    \"page\": 1,\n    \"index\": 0,\n    \"width\": 1920,\n    \"height\": 1080,\n    \"format\": \"rgb\",\n    \"data\": \"base64-encoded-png...\"\n  }]\n}\n```\n\n**Supported formats:** RGB, RGBA, Grayscale\n**Auto-detected:** JPEG, PNG, and other embedded formats\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📂 Path Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**Absolute paths** (v1.3.0+) - Direct file access:\n```json\n{ \"path\": \"C:\\\\Users\\\\John\\\\file.pdf\" }\n{ \"path\": \"\u002Fhome\u002Fuser\u002Ffile.pdf\" }\n```\n\n**Relative paths** - Workspace files:\n```json\n{ \"path\": \"docs\u002Freport.pdf\" }\n{ \"path\": \".\u002F2024\u002FQ1.pdf\" }\n```\n\n**Configure working directory:**\n```json\n{\n  \"mcpServers\": {\n    \"pdf-reader-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"],\n      \"cwd\": \"\u002Fpath\u002Fto\u002Fdocuments\"\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📊 Large PDF Strategies\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**Strategy 1: Page ranges**\n```json\n{ \"sources\": [{ \"path\": \"big.pdf\", \"pages\": \"1-20\" }] }\n```\n\n**Strategy 2: Progressive loading**\n```json\n\u002F\u002F Step 1: Get page count\n{ \"sources\": [{ \"path\": \"big.pdf\" }], \"include_full_text\": false }\n\n\u002F\u002F Step 2: Extract sections\n{ \"sources\": [{ \"path\": \"big.pdf\", \"pages\": \"50-75\" }] }\n```\n\n**Strategy 3: Parallel batching**\n```json\n{\n  \"sources\": [\n    { \"path\": \"big.pdf\", \"pages\": \"1-50\" },\n    { \"path\": \"big.pdf\", \"pages\": \"51-100\" }\n  ]\n}\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 🔧 Troubleshooting\n\n### \"Absolute paths are not allowed\"\n\n**Solution:** Upgrade to v1.3.0+\n\n```bash\nnpm update @sylphx\u002Fpdf-reader-mcp\n```\n\nRestart your MCP client completely.\n\n---\n\n### \"File not found\"\n\n**Causes:**\n- File doesn't exist at path\n- Wrong working directory\n- Permission issues\n\n**Solutions:**\n\nUse absolute path:\n```json\n{ \"path\": \"C:\\\\Full\\\\Path\\\\file.pdf\" }\n```\n\nOr configure `cwd`:\n```json\n{\n  \"pdf-reader-mcp\": {\n    \"command\": \"npx\",\n    \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"],\n    \"cwd\": \"\u002Fpath\u002Fto\u002Fdocs\"\n  }\n}\n```\n\n---\n\n### \"No tools showing up\"\n\n**Solution:**\n\n```bash\nnpm cache clean --force\nrm -rf node_modules package-lock.json\nnpm install @sylphx\u002Fpdf-reader-mcp@latest\n```\n\nRestart MCP client completely.\n\n---\n\n## 🌐 HTTP Transport (Remote Access)\n\nBy default, PDF Reader MCP uses stdio transport for local use. You can also run it as an HTTP server for remote access from multiple machines.\n\n### Quick Start\n\n```bash\n# Run as HTTP server on port 8080\nMCP_TRANSPORT=http npx @sylphx\u002Fpdf-reader-mcp\n```\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_TRANSPORT` | `stdio` | Transport type: `stdio` or `http` |\n| `MCP_HTTP_PORT` | `8080` | HTTP server port |\n| `MCP_HTTP_HOST` | `0.0.0.0` | HTTP server hostname |\n| `MCP_API_KEY` | - | Optional API key for authentication |\n\n### Docker Deployment\n\n```dockerfile\nFROM oven\u002Fbun:1\nWORKDIR \u002Fapp\nRUN bun add @sylphx\u002Fpdf-reader-mcp\nENV MCP_TRANSPORT=http\nENV MCP_HTTP_PORT=8080\nEXPOSE 8080\nCMD [\"bun\", \"node_modules\u002F@sylphx\u002Fpdf-reader-mcp\u002Fdist\u002Findex.js\"]\n```\n\n### MCP Client Configuration (HTTP)\n\n```json\n{\n  \"servers\": {\n    \"pdf-reader\": {\n      \"type\": \"http\",\n      \"url\": \"https:\u002F\u002Fyour-server.com\u002Fmcp\",\n      \"headers\": {\n        \"X-API-Key\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `\u002Fmcp` | POST | JSON-RPC endpoint |\n| `\u002Fmcp\u002Fhealth` | GET | Health check |\n\n---\n\n## 🏗️ Architecture\n\n### Tech Stack\n\n| Component | Technology |\n|:----------|:-----------|\n| **Runtime** | Node.js 22+ ESM |\n| **PDF Engine** | PDF.js (Mozilla) |\n| **Validation** | Zod + JSON Schema |\n| **Protocol** | MCP SDK |\n| **Language** | TypeScript (strict) |\n| **Testing** | Vitest (103 tests) |\n| **Quality** | Biome (50x faster) |\n| **CI\u002FCD** | GitHub Actions |\n\n### Design Principles\n\n- 🔒 **Security First** - Flexible paths with secure defaults\n- 🎯 **Simple Interface** - One tool, all operations\n- ⚡ **Performance** - Parallel processing, efficient memory\n- 🛡️ **Reliability** - Per-page isolation, detailed errors\n- 🧪 **Quality** - 94%+ coverage, strict TypeScript\n- 📝 **Type Safety** - No `any` types, strict mode\n- 🔄 **Backward Compatible** - Smooth upgrades always\n\n---\n\n## 🧪 Development\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Setup & Scripts\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**Prerequisites:**\n- Node.js >= 22.0.0\n- pnpm (recommended) or npm\n\n**Setup:**\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp.git\ncd pdf-reader-mcp\npnpm install && pnpm build\n```\n\n**Scripts:**\n```bash\npnpm run build       # Build TypeScript\npnpm run test        # Run 103 tests\npnpm run test:cov    # Coverage (94%+)\npnpm run check       # Lint + format\npnpm run check:fix   # Auto-fix\npnpm run benchmark   # Performance tests\n```\n\n**Quality:**\n- ✅ 103 tests\n- ✅ 94%+ coverage\n- ✅ 98%+ function coverage\n- ✅ Zero lint errors\n- ✅ Strict TypeScript\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Contributing\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**Quick Start:**\n1. Fork repository\n2. Create branch: `git checkout -b feature\u002Fawesome`\n3. Make changes: `pnpm test`\n4. Format: `pnpm run check:fix`\n5. Commit: Use [Conventional Commits](https:\u002F\u002Fwww.conventionalcommits.org\u002F)\n6. Open PR\n\n**Commit Format:**\n```\nfeat(images): add WebP support\nfix(paths): handle UNC paths\ndocs(readme): update examples\n```\n\nSee [CONTRIBUTING.md](.\u002FCONTRIBUTING.md)\n\n\u003C\u002Fdetails>\n\n---\n\n## 📚 Documentation\n\n- 📖 [Full Docs](https:\u002F\u002FSylphxAI.github.io\u002Fpdf-reader-mcp\u002F) - Complete guides\n- 🚀 [Getting Started](.\u002Fdocs\u002Fguide\u002Fgetting-started.md) - Quick start\n- 📘 [API Reference](.\u002Fdocs\u002Fapi\u002FREADME.md) - Detailed API\n- 🏗️ [Design](.\u002Fdocs\u002Fdesign\u002Findex.md) - Architecture\n- ⚡ [Performance](.\u002Fdocs\u002Fperformance\u002Findex.md) - Benchmarks\n- 🔍 [Comparison](.\u002Fdocs\u002Fcomparison\u002Findex.md) - vs. alternatives\n\n---\n\n## 🗺️ Roadmap\n\n**✅ Completed**\n- [x] Image extraction (v1.1.0)\n- [x] 5-10x parallel speedup (v1.1.0)\n- [x] Y-coordinate ordering (v1.2.0)\n- [x] Absolute paths (v1.3.0)\n- [x] 94%+ test coverage (v1.3.0)\n\n**🚀 Next**\n- [ ] OCR for scanned PDFs\n- [ ] Annotation extraction\n- [ ] Form field extraction\n- [ ] Table detection\n- [ ] 100+ MB streaming\n- [ ] Advanced caching\n- [ ] PDF generation\n\nVote at [Discussions](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fdiscussions)\n\n---\n\n## 🏆 Recognition\n\n**Featured on:**\n- [Smithery](https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@sylphx\u002Fpdf-reader-mcp) - MCP directory\n- [Glama](https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002F@sylphx\u002Fpdf-reader-mcp) - AI marketplace\n- [MseeP.ai](https:\u002F\u002Fmseep.ai\u002Fapp\u002FSylphxAI-pdf-reader-mcp) - Security validated\n\n**Trusted worldwide** • **Enterprise adoption** • **Battle-tested**\n\n---\n\n## 🤝 Support\n\n[![GitHub Issues](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues\u002FSylphxAI\u002Fpdf-reader-mcp?style=flat-square)](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fissues)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002FYOUR_DISCORD_ID?style=flat-square&logo=discord)](https:\u002F\u002Fdiscord.gg\u002Fsylphx)\n\n- 🐛 [Bug Reports](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fissues)\n- 💬 [Discussions](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fdiscussions)\n- 📖 [Documentation](https:\u002F\u002FSylphxAI.github.io\u002Fpdf-reader-mcp\u002F)\n- 📧 [Email](mailto:hi@sylphx.com)\n\n**Show Your Support:**\n⭐ Star • 👀 Watch • 🐛 Report bugs • 💡 Suggest features • 🔀 Contribute\n\n---\n\n## 📊 Stats\n\n![Stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FSylphxAI\u002Fpdf-reader-mcp?style=social)\n![Forks](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fforks\u002FSylphxAI\u002Fpdf-reader-mcp?style=social)\n![Downloads](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdm\u002F@sylphx\u002Fpdf-reader-mcp)\n![Contributors](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcontributors\u002FSylphxAI\u002Fpdf-reader-mcp)\n\n**103 Tests** • **94%+ Coverage** • **Production Ready**\n\n---\n\n## 📄 License\n\nMIT © [Sylphx](https:\u002F\u002Fsylphx.com)\n\n---\n\n## 🙏 Credits\n\nBuilt with:\n- [PDF.js](https:\u002F\u002Fmozilla.github.io\u002Fpdf.js\u002F) - Mozilla PDF engine\n- [Bun](https:\u002F\u002Fbun.sh) - Fast JavaScript runtime\n\nSpecial thanks to the open source community ❤️\n\n## Powered by Sylphx\n\nThis project uses the following [@sylphx](https:\u002F\u002Fgithub.com\u002FSylphxAI) packages:\n\n- [@sylphx\u002Fmcp-server-sdk](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fmcp-server-sdk) - MCP server framework\n- [@sylphx\u002Fvex](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fvex) - Schema validation\n- [@sylphx\u002Fbiome-config](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fbiome-config) - Biome configuration\n- [@sylphx\u002Ftsconfig](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Ftsconfig) - TypeScript configuration\n- [@sylphx\u002Fbump](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fbump) - Version management\n- [@sylphx\u002Fdoctor](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fdoctor) - Project health checker\n\n---\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FSylphxAI_pdf-reader-mcp_readme_f8e8adf1d2f7.png)](https:\u002F\u002Fstar-history.com\u002F#SylphxAI\u002Fpdf-reader-mcp&Date)\n\n---\n\n\u003Cdiv align=\"center\">\n\u003Csub>Built with ❤️ by \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FSylphxAI\">Sylphx\u003C\u002Fa>\u003C\u002Fsub>\n\u003C\u002Fdiv>\n","\u003Cdiv align=\"center\">\n\n# 📄 @sylphx\u002Fpdf-reader-mcp\n\n> 面向 AI 代理的生产级 PDF 处理服务器\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@sylphx\u002Fpdf-reader-mcp?style=flat-square)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@sylphx\u002Fpdf-reader-mcp)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue?style=flat-square)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![CI\u002FCD](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fci.yml?style=flat-square&label=CI\u002FCD)](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Factions\u002Fworkflows\u002Fci.yml)\n[![codecov](https:\u002F\u002Fimg.shields.io\u002Fcodecov\u002Fc\u002Fgithub\u002FSylphxAI\u002Fpdf-reader-mcp?style=flat-square)](https:\u002F\u002Fcodecov.io\u002Fgh\u002FSylphxAI\u002Fpdf-reader-mcp)\n[![coverage](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcoverage-94.17%25-brightgreen?style=flat-square)](https:\u002F\u002Fpdf-reader-msu3esos4-sylphx.vercel.app)\n[![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-5.0-blue.svg?style=flat-square)](https:\u002F\u002Fwww.typescriptlang.org\u002F)\n[![Downloads](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdm\u002F@sylphx\u002Fpdf-reader-mcp?style=flat-square)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@sylphx\u002Fpdf-reader-mcp)\n\n**并行处理速度提升 5–10 倍** • **按 Y 坐标内容排序** • **测试覆盖率 94%+** • **103 项测试全部通过**\n\n\u003Ca href=\"https:\u002F\u002Fmseep.ai\u002Fapp\u002FSylphxAI-pdf-reader-mcp\">\n\u003Cimg src=\"https:\u002F\u002Fmseep.net\u002Fpr\u002FSylphxAI-pdf-reader-mcp-badge.png\" alt=\"安全验证\" width=\"200\"\u002F>\n\u003C\u002Fa>\n\n\u003C\u002Fdiv>\n\n---\n\n## 🚀 概述\n\nPDF Reader MCP 是一个**生产就绪**的模型上下文协议服务器，为 AI 代理提供**企业级 PDF 处理能力**。以无与伦比的性能和可靠性提取文本、图像和元数据。\n\n**问题所在：**\n```typescript\n\u002F\u002F 传统 PDF 处理方式\n- 逐页处理（速度慢）\n- 内容无自然顺序\n- 路径处理复杂\n- 错误隔离性差\n```\n\n**解决方案：**\n```typescript\n\u002F\u002F PDF Reader MCP\n- 并行处理速度提升 5–10 倍 ⚡\n- 基于 Y 坐标的排序 📐\n- 灵活的路径支持（绝对\u002F相对）🎯\n- 每页独立错误恢复 🛡️\n- 测试覆盖率 94%+ ✅\n```\n\n**结果：可扩展的生产级 PDF 处理方案。**\n\n---\n\n## ⚡ 核心特性\n\n### 性能\n\n- 🚀 **速度提升 5–10 倍**，自动并行化\n- ⚡ **12,933 ops\u002Fsec** 错误处理，5,575 ops\u002Fsec 文本提取\n- 💨 **多核利用**，可在几秒钟内处理 50 页 PDF\n- 📦 **轻量级**，依赖极少\n\n### 开发者体验\n\n- 🎯 **路径灵活性** - 支持绝对路径和相对路径，兼容 Windows 和 Unix（v1.3.0）\n- 🖼️ **智能排序** - 基于 Y 坐标的排序保留文档布局\n- 🛡️ **类型安全** - 完全 TypeScript，启用严格模式\n- 📚 **实战检验** - 103 项测试，覆盖率 94%+，函数覆盖率 98%+\n- 🎨 **简单 API** - 单一工具优雅地完成所有操作\n\n---\n\n## 📊 性能基准测试\n\n生产环境实测表现：\n\n| 操作 | ops\u002Fsec | 性能 | 使用场景 |\n|-----------|---------|-------------|----------|\n| **错误处理** | 12,933 | ⚡⚡⚡⚡⚡ | 验证与安全性 |\n| **提取全文** | 5,575 | ⚡⚡⚡⚡ | 文档分析 |\n| **提取单页** | 5,329 | ⚡⚡⚡⚡ | 单页操作 |\n| **多页处理** | 5,242 | ⚡⚡⚡⚡ | 批量处理 |\n| **仅提取元数据** | 4,912 | ⚡⚡⚡ | 快速检查 |\n\n### 并行处理加速效果\n\n| 文档 | 串行 | 并行 | 加速倍数 |\n|----------|-----------|----------|---------|\n| **10 页 PDF** | ~2s | ~0.3s | **5–8 倍更快** |\n| **50 页 PDF** | ~10s | ~1s | **10 倍更快** |\n| **100+ 页** | ~20s | ~2s | **随 CPU 核心线性扩展** |\n\n*基准测试结果因 PDF 复杂度和系统资源而异。*\n\n---\n\n## 📦 安装\n\n### Claude Code\n\n```bash\nclaude mcp add pdf-reader -- npx @sylphx\u002Fpdf-reader-mcp\n```\n\n### Claude Desktop\n\n将以下内容添加到 `claude_desktop_config.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-reader\": {\n      \"command\": \"npx\",\n      \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"]\n    }\n  }\n}\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📍 配置文件位置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n- **macOS**: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~\u002F.config\u002FClaude\u002Fclaude_desktop_config.json`\n\n\u003C\u002Fdetails>\n\n### VS Code\n\n```bash\ncode --add-mcp '{\"name\":\"pdf-reader\",\"command\":\"npx\",\"args\":[\"@sylphx\u002Fpdf-reader-mcp\"]}'\n```\n\n### Cursor\n\n1. 打开 **设置** → **MCP** → **添加新 MCP 服务器**\n2. 选择 **命令** 类型\n3. 输入：`npx @sylphx\u002Fpdf-reader-mcp`\n\n### Windsurf\n\n将以下内容添加到你的 Windsurf MCP 配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-reader\": {\n      \"command\": \"npx\",\n      \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"]\n    }\n  }\n}\n```\n\n### Cline\n\n将以下内容添加到 Cline 的 MCP 设置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-reader\": {\n      \"command\": \"npx\",\n      \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"]\n    }\n  }\n}\n```\n\n### Warp\n\n1. 进入 **设置** → **AI** → **管理 MCP 服务器** → **添加**\n2. 命令：`npx`，参数：`@sylphx\u002Fpdf-reader-mcp`\n\n### Smithery（一键安装）\n\n```bash\nnpx -y @smithery\u002Fcli install @sylphx\u002Fpdf-reader-mcp --client claude\n```\n\n### 手动安装\n\n```bash\n# 快速启动 - 无需安装\nnpx @sylphx\u002Fpdf-reader-mcp\n\n# 或全局安装\nnpm install -g @sylphx\u002Fpdf-reader-mcp\n```\n\n---\n\n## 🎯 快速入门\n\n### 基本用法\n\n```json\n{\n  \"sources\": [{\n    \"path\": \"documents\u002Freport.pdf\"\n  }],\n  \"include_full_text\": true,\n  \"include_metadata\": true,\n  \"include_page_count\": true\n}\n```\n\n**结果：**\n- ✅ 提取了完整文本内容\n- ✅ 包含 PDF 元数据（作者、标题、日期等）\n- ✅ 统计了总页数\n- ✅ 保留了未修改部分的结构共享\n\n### 提取指定页面\n\n```json\n{\n  \"sources\": [{\n    \"path\": \"documents\u002Fmanual.pdf\",\n    \"pages\": \"1-5,10,15-20\"\n  }],\n  \"include_full_text\": true\n}\n```\n\n### 绝对路径（v1.3.0+）\n\n```json\n\u002F\u002F Windows - 两种格式均可！\n{\n  \"sources\": [{\n    \"path\": \"C:\\\\Users\\\\John\\\\Documents\\\\report.pdf\"\n  }],\n  \"include_full_text\": true\n}\n\n\u002F\u002F Unix\u002FMac\n{\n  \"sources\": [{\n    \"path\": \"\u002Fhome\u002Fuser\u002Fdocuments\u002Fcontract.pdf\"\n  }],\n  \"include_full_text\": true\n}\n```\n\n**不再出现** `\"不允许使用绝对路径\"` **错误！**\n\n### 提取图像并保持自然顺序\n\n```json\n{\n  \"sources\": [{\n    \"path\": \"presentation.pdf\",\n    \"pages\": [1, 2, 3]\n  }],\n  \"include_images\": true,\n  \"include_full_text\": true\n}\n```\n\n**响应包含：**\n- 文本和图像按**文档原始顺序**排列（按 Y 坐标排序）\n- Base64 编码的图像及元数据（宽度、高度、格式）\n- 保留自然阅读顺序，便于 AI 理解\n\n### 批量处理\n\n```json\n{\n  \"sources\": [\n    { \"path\": \"C:\\\\Reports\\\\Q1.pdf\", \"pages\": \"1-10\" },\n    { \"path\": \"\u002Fhome\u002Fuser\u002FQ2.pdf\", \"pages\": \"1-10\" },\n    { \"url\": \"https:\u002F\u002Fexample.com\u002FQ3.pdf\" }\n  ],\n  \"include_full_text\": true\n}\n```\n\n⚡ **所有 PDF 将自动并行处理！**\n\n---\n\n## ✨ 特性\n\n### 核心功能\n- ✅ **文本提取** - 整个文档或指定页面，支持智能解析\n- ✅ **图像提取** - Base64 编码，附带完整元数据（宽度、高度、格式）\n- ✅ **内容排序** - 基于 Y 坐标的布局保持，确保自然的阅读顺序\n- ✅ **元数据提取** - 作者、标题、创建日期及自定义属性\n- ✅ **页数统计** - 快速统计，无需加载全部内容\n- ✅ **双源支持** - 本地文件（绝对路径或相对路径）和 HTTP\u002FHTTPS URL\n- ✅ **批量处理** - 可同时处理多个 PDF 文件\n\n### 高级特性\n- ⚡ **5-10倍性能提升** - 使用 Promise.all 并行处理页面\n- 🎯 **智能分页** - 支持提取范围，如“1-5,10-15,20”\n- 🖼️ **多格式图像** - 自动检测 RGB、RGBA 和灰度图像\n- 🛡️ **路径灵活性** - 支持 Windows、Unix 路径以及相对路径（v1.3.0）\n- 🔍 **错误容错性** - 每页独立错误处理，并提供详细错误信息\n- 📏 **大文件支持** - 高效流式处理与内存管理\n- 📝 **类型安全** - 完全 TypeScript 实现，启用严格模式\n\n---\n\n## 🆕 v1.3.0 新增内容\n\n### 🎉 现已支持绝对路径！\n\n```json\n\u002F\u002F ✅ Windows\n{ \"path\": \"C:\\\\Users\\\\John\\\\Documents\\\\report.pdf\" }\n{ \"path\": \"C:\u002FUsers\u002FJohn\u002FDocuments\u002Freport.pdf\" }\n\n\u002F\u002F ✅ Unix\u002FMac\n{ \"path\": \"\u002Fhome\u002Fjohn\u002Fdocuments\u002Freport.pdf\" }\n{ \"path\": \"\u002FUsers\u002Fjohn\u002FDocuments\u002Freport.pdf\" }\n\n\u002F\u002F ✅ 相对路径（仍可使用）\n{ \"path\": \"documents\u002Freport.pdf\" }\n```\n\n**其他改进：**\n- 🐛 修复了 Zod 验证错误处理问题\n- 📦 更新所有依赖至最新版本\n- ✅ 103 项测试通过，覆盖率保持在 94% 以上\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📋 查看完整变更日志\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**v1.2.0 - 内容排序**\n- 基于 Y 坐标对文本和图像进行排序\n- 为 AI 模型提供自然的阅读顺序\n- 智能行分组\n\n**v1.1.0 - 图像提取与性能**\n- Base64 编码图像提取\n- 并行处理使速度提升 10 倍\n- 全面的测试覆盖（94%+）\n\n[查看完整变更日志 →](.\u002FCHANGELOG.md)\n\n\u003C\u002Fdetails>\n\n---\n\n## 📖 API 参考\n\n### `read_pdf` 工具\n\n一个工具即可完成所有 PDF 操作。\n\n#### 参数\n\n| 参数            | 类型      | 描述                                      | 默认值 |\n|-----------------|-----------|-------------------------------------------|--------|\n| `sources`       | 数组      | 待处理的 PDF 源列表                       | 必填   |\n| `include_full_text` | 布尔值  | 提取完整文本内容                          | `false`|\n| `include_metadata` | 布尔值  | 提取 PDF 元数据                           | `true` |\n| `include_page_count` | 布尔值  | 包含总页数                                | `true` |\n| `include_images` | 布尔值  | 提取嵌入式图像                            | `false`|\n\n#### 源对象\n\n```typescript\n{\n  path?: string;        \u002F\u002F 本地文件路径（绝对或相对）\n  url?: string;         \u002F\u002F PDF 的 HTTP\u002FHTTPS URL\n  pages?: string | number[];  \u002F\u002F 要提取的页面：“1-5,10”或 [1,2,3]\n}\n```\n\n#### 示例\n\n**仅元数据（快速）：**\n```json\n{\n  \"sources\": [{ \"path\": \"large.pdf\" }],\n  \"include_metadata\": true,\n  \"include_page_count\": true,\n  \"include_full_text\": false\n}\n```\n\n**从 URL：**\n```json\n{\n  \"sources\": [{\n    \"url\": \"https:\u002F\u002Farxiv.org\u002Fpdf\u002F2301.00001.pdf\"\n  }],\n  \"include_full_text\": true\n}\n```\n\n**指定页面范围：**\n```json\n{\n  \"sources\": [{\n    \"path\": \"manual.pdf\",\n    \"pages\": \"1-5,10-15,20\"  \u002F\u002F 提取第 1、2、3、4、5、10、11、12、13、14、15、20 页\n  }]\n}\n```\n\n---\n\n## 🔧 高级用法\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📐 基于 Y 坐标的内容排序\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n内容按 Y 坐标以自然阅读顺序返回：\n\n```\n文档布局：\n┌─────────────────────┐\n│ [标题]       Y:100 │\n│ [图片]       Y:150 │\n│ [文本]       Y:400 │\n│ [照片 A]     Y:500 │\n│ [照片 B]     Y:550 │\n└─────────────────────┘\n\n响应顺序：\n[\n  { type: \"text\", text: \"标题...\" },\n  { type: \"image\", data: \"...\" },\n  { type: \"text\", text: \"...\" },\n  { type: \"image\", data: \"...\" },\n  { type: \"image\", data: \"...\" }\n]\n```\n\n**优势：**\n- AI 能够理解空间关系\n- 更自然的文档理解\n- 非常适合视觉增强型模型\n- 自动多行文本分组\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🖼️ 图像提取\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**启用图像提取：**\n```json\n{\n  \"sources\": [{ \"path\": \"manual.pdf\" }],\n  \"include_images\": true\n}\n```\n\n**响应格式：**\n```json\n{\n  \"images\": [{\n    \"page\": 1,\n    \"index\": 0,\n    \"width\": 1920,\n    \"height\": 1080,\n    \"format\": \"rgb\",\n    \"data\": \"base64-encoded-png...\"\n  }]\n}\n```\n\n**支持的格式：** RGB、RGBA、灰度  \n**自动检测：** JPEG、PNG 等嵌入格式\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📂 路径配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**绝对路径**（v1.3.0+）- 直接访问文件：\n```json\n{ \"path\": \"C:\\\\Users\\\\John\\\\file.pdf\" }\n{ \"path\": \"\u002Fhome\u002Fuser\u002Ffile.pdf\" }\n```\n\n**相对路径** - 工作目录中的文件：\n```json\n{ \"path\": \"docs\u002Freport.pdf\" }\n{ \"path\": \".\u002F2024\u002FQ1.pdf\" }\n```\n\n**配置工作目录：**\n```json\n{\n  \"mcpServers\": {\n    \"pdf-reader-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"],\n      \"cwd\": \"\u002Fpath\u002Fto\u002Fdocuments\"\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📊 大型 PDF 处理策略\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**策略 1：指定页面范围**\n```json\n{ \"sources\": [{ \"path\": \"big.pdf\", \"pages\": \"1-20\" }] }\n```\n\n**策略 2：逐步加载**\n```json\n\u002F\u002F 步骤 1：获取页数\n{ \"sources\": [{ \"path\": \"big.pdf\" }], \"include_full_text\": false }\n\n\u002F\u002F 步骤 2：提取部分页面\n{ \"sources\": [{ \"path\": \"big.pdf\", \"pages\": \"50-75\" }] }\n```\n\n**策略 3：并行分批处理**\n```json\n{\n  \"sources\": [\n    { \"path\": \"big.pdf\", \"pages\": \"1-50\" },\n    { \"path\": \"big.pdf\", \"pages\": \"51-100\" }\n  ]\n}\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 🔧 故障排除\n\n### “不允许使用绝对路径”\n\n**解决方案：** 升级到 v1.3.0+\n\n```bash\nnpm update @sylphx\u002Fpdf-reader-mcp\n```\n\n然后完全重启您的 MCP 客户端。\n\n---\n\n### “文件未找到”\n\n**原因：**\n- 文件路径不存在\n- 工作目录设置错误\n- 权限不足\n\n**解决方案：**\n\n使用绝对路径：\n```json\n{ \"path\": \"C:\\\\Full\\\\Path\\\\file.pdf\" }\n```\n\n或者配置 `cwd`：\n```json\n{\n  \"pdf-reader-mcp\": {\n    \"command\": \"npx\",\n    \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"],\n    \"cwd\": \"\u002Fpath\u002Fto\u002Fdocs\"\n  }\n}\n```\n\n---\n\n### “未显示任何工具”\n\n**解决方案：**\n\n```bash\nnpm cache clean --force\nrm -rf node_modules package-lock.json\nnpm install @sylphx\u002Fpdf-reader-mcp@latest\n```\n\n然后完全重启 MCP 客户端。\n\n---\n\n## 🌐 HTTP 传输（远程访问）\n\n默认情况下，PDF Reader MCP 使用 stdio 传输进行本地使用。您也可以将其作为 HTTP 服务器运行，以便从多台机器进行远程访问。\n\n### 快速入门\n\n```bash\n# 以 HTTP 服务器模式运行，监听 8080 端口\nMCP_TRANSPORT=http npx @sylphx\u002Fpdf-reader-mcp\n```\n\n### 环境变量\n\n| 变量              | 默认值 | 描述                                       |\n|-------------------|--------|--------------------------------------------|\n| `MCP_TRANSPORT`   | `stdio` | 传输方式：`stdio` 或 `http`                |\n| `MCP_HTTP_PORT`   | `8080` | HTTP 服务器监听端口                       |\n| `MCP_HTTP_HOST`   | `0.0.0.0` | HTTP 服务器绑定的主机名                   |\n| `MCP_API_KEY`     | -      | 可选的 API 密钥，用于身份验证            |\n\n### Docker 部署\n\n```dockerfile\nFROM oven\u002Fbun:1\nWORKDIR \u002Fapp\nRUN bun add @sylphx\u002Fpdf-reader-mcp\nENV MCP_TRANSPORT=http\nENV MCP_HTTP_PORT=8080\nEXPOSE 8080\nCMD [\"bun\", \"node_modules\u002F@sylphx\u002Fpdf-reader-mcp\u002Fdist\u002Findex.js\"]\n```\n\n### MCP 客户端配置（HTTP）\n\n```json\n{\n  \"servers\": {\n    \"pdf-reader\": {\n      \"type\": \"http\",\n      \"url\": \"https:\u002F\u002Fyour-server.com\u002Fmcp\",\n      \"headers\": {\n        \"X-API-Key\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### 端点\n\n| 端点       | 方法   | 描述               |\n|------------|--------|--------------------|\n| `\u002Fmcp`     | POST   | JSON-RPC 端点      |\n| `\u002Fmcp\u002Fhealth` | GET   | 健康检查           |\n\n---\n\n## 🏗️ 架构\n\n### 技术栈\n\n| 组件         | 技术                     |\n|--------------|--------------------------|\n| **运行时**   | Node.js 22+ ESM          |\n| **PDF 引擎** | PDF.js（Mozilla）        |\n| **验证**     | Zod + JSON Schema        |\n| **协议**     | MCP SDK                  |\n| **语言**     | TypeScript（严格模式）   |\n| **测试**     | Vitest（103 个测试）    |\n| **质量**     | Biome（快 50 倍）       |\n| **CI\u002FCD**    | GitHub Actions           |\n\n### 设计原则\n\n- 🔒 **安全第一** - 灵活路径，安全默认\n- 🎯 **简单接口** - 一个工具，所有操作\n- ⚡ **性能** - 并行处理，高效内存\n- 🛡️ **可靠性** - 每页隔离，详细错误\n- 🧪 **质量** - 94%+ 覆盖率，严格 TypeScript\n- 📝 **类型安全** - 无 `any` 类型，严格模式\n- 🔄 **向后兼容** - 始终平滑升级\n\n---\n\n## 🧪 开发\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>设置与脚本\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**先决条件：**\n- Node.js >= 22.0.0\n- pnpm（推荐）或 npm\n\n**设置：**\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp.git\ncd pdf-reader-mcp\npnpm install && pnpm build\n```\n\n**脚本：**\n```bash\npnpm run build       # 编译 TypeScript\npnpm run test        # 运行 103 个测试\npnpm run test:cov    # 覆盖率（94%+）\npnpm run check       # 代码检查 + 格式化\npnpm run check:fix   # 自动修复\npnpm run benchmark   # 性能测试\n```\n\n**质量：**\n- ✅ 103 个测试\n- ✅ 94%+ 覆盖率\n- ✅ 98%+ 函数覆盖率\n- ✅ 无 lint 错误\n- ✅ 严格 TypeScript\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>贡献\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr\u002F>\n\n**快速入门：**\n1. 分支仓库\n2. 创建分支：`git checkout -b feature\u002Fawesome`\n3. 修改代码：`pnpm test`\n4. 格式化：`pnpm run check:fix`\n5. 提交：使用 [Conventional Commits](https:\u002F\u002Fwww.conventionalcommits.org\u002F)\n6. 打开 PR\n\n**提交格式：**\n```\nfeat(images): 添加 WebP 支持\nfix(paths): 处理 UNC 路径\ndocs(readme): 更新示例\n```\n\n详情请参阅 [CONTRIBUTING.md](.\u002FCONTRIBUTING.md)\n\n\u003C\u002Fdetails>\n\n---\n\n## 📚 文档\n\n- 📖 [完整文档](https:\u002F\u002FSylphxAI.github.io\u002Fpdf-reader-mcp\u002F) - 全面指南\n- 🚀 [入门指南](.\u002Fdocs\u002Fguide\u002Fgetting-started.md) - 快速开始\n- 📘 [API 参考](.\u002Fdocs\u002Fapi\u002FREADME.md) - 详细 API\n- 🏗️ [设计文档](.\u002Fdocs\u002Fdesign\u002Findex.md) - 架构说明\n- ⚡ [性能文档](.\u002Fdocs\u002Fperformance\u002Findex.md) - 基准测试\n- 🔍 [对比文档](.\u002Fdocs\u002Fcomparison\u002Findex.md) - 与替代方案比较\n\n---\n\n## 🗺️ 路线图\n\n**✅ 已完成**\n- [x] 图像提取（v1.1.0）\n- [x] 并行加速 5-10 倍（v1.1.0）\n- [x] Y 坐标排序（v1.2.0）\n- [x] 绝对路径支持（v1.3.0）\n- [x] 测试覆盖率 94%+（v1.3.0）\n\n**🚀 下一步**\n- [ ] 扫描 PDF 的 OCR\n- [ ] 注释提取\n- [ ] 表单字段提取\n- [ ] 表格检测\n- [ ] 100+ MB 流式处理\n- [ ] 高级缓存\n- [ ] PDF 生成\n\n欢迎在 [讨论区](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fdiscussions) 投票！\n\n---\n\n## 🏆 认可\n\n**被以下平台收录：**\n- [Smithery](https:\u002F\u002Fsmithery.ai\u002Fserver\u002F@sylphx\u002Fpdf-reader-mcp) - MCP 目录\n- [Glama](https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002F@sylphx\u002Fpdf-reader-mcp) - AI 市场\n- [MseeP.ai](https:\u002F\u002Fmseep.ai\u002Fapp\u002FSylphxAI-pdf-reader-mcp) - 安全认证\n\n**全球信赖** • **企业采用** • **实战检验**\n\n---\n\n## 🤝 支持\n\n[![GitHub Issues](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues\u002FSylphxAI\u002Fpdf-reader-mcp?style=flat-square)](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fissues)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002FYOUR_DISCORD_ID?style=flat-square&logo=discord)](https:\u002F\u002Fdiscord.gg\u002Fsylphx)\n\n- 🐛 [Bug Reports](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fissues)\n- 💬 [Discussions](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fdiscussions)\n- 📖 [Documentation](https:\u002F\u002FSylphxAI.github.io\u002Fpdf-reader-mcp\u002F)\n- 📧 [Email](mailto:hi@sylphx.com)\n\n**请支持我们：**\n⭐ 星标 • 👀 关注 • 🐛 报告 bug • 💡 提供建议 • 🔀 贡献\n\n---\n\n## 📊 统计\n\n![星标](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FSylphxAI\u002Fpdf-reader-mcp?style=social)\n![分叉](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fforks\u002FSylphxAI\u002Fpdf-reader-mcp?style=social)\n![下载量](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdm\u002F@sylphx\u002Fpdf-reader-mcp)\n![贡献者](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcontributors\u002FSylphxAI\u002Fpdf-reader-mcp)\n\n**103 个测试** • **94%+ 覆盖率** • **生产就绪**\n\n---\n\n## 📄 许可证\n\nMIT © [Sylphx](https:\u002F\u002Fsylphx.com)\n\n---\n\n## 🙏 致谢\n\n基于以下技术构建：\n- [PDF.js](https:\u002F\u002Fmozilla.github.io\u002Fpdf.js\u002F) - Mozilla PDF 引擎\n- [Bun](https:\u002F\u002Fbun.sh) - 高效 JavaScript 运行时\n\n特别感谢开源社区 ❤️\n\n## 由 Sylphx 提供支持\n\n本项目使用了以下 [@sylphx](https:\u002F\u002Fgithub.com\u002FSylphxAI) 包：\n\n- [@sylphx\u002Fmcp-server-sdk](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fmcp-server-sdk) - MCP 服务器框架\n- [@sylphx\u002Fvex](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fvex) - 模式验证\n- [@sylphx\u002Fbiome-config](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fbiome-config) - Biome 配置\n- [@sylphx\u002Ftsconfig](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Ftsconfig) - TypeScript 配置\n- [@sylphx\u002Fbump](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fbump) - 版本管理\n- [@sylphx\u002Fdoctor](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fdoctor) - 项目健康检查\n\n---\n\n## 星标历史\n\n[![星标历史图表](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FSylphxAI_pdf-reader-mcp_readme_f8e8adf1d2f7.png)](https:\u002F\u002Fstar-history.com\u002F#SylphxAI\u002Fpdf-reader-mcp&Date)\n\n---\n\n\u003Cdiv align=\"center\">\n\u003Csub>由 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FSylphxAI\">Sylphx\u003C\u002Fa> 用心打造\u003C\u002Fsub>\n\u003C\u002Fdiv>","# pdf-reader-mcp 快速上手指南\n\n`pdf-reader-mcp` 是一个生产级的 Model Context Protocol (MCP) 服务器，专为 AI Agent 设计，提供企业级的 PDF 处理能力。它支持并行处理（速度提升 5-10 倍）、基于 Y 轴坐标的自然内容排序以及高容错率的页面提取。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **Node.js**: 建议安装 LTS 版本（v18 或更高），因为该工具通过 `npx` 运行。\n*   **AI 客户端**: 已安装支持 MCP 协议的客户端（如 Claude Desktop, Cursor, Windsurf, Cline, VS Code 等）。\n*   **网络环境**: 能够访问 npm registry 以拉取包。\n    *   *国内加速建议*: 如果下载缓慢，可配置淘宝镜像源：\n      ```bash\n      npm config set registry https:\u002F\u002Fregistry.npmmirror.com\n      ```\n\n## 安装步骤\n\n根据您的使用场景，选择以下任一方式进行配置：\n\n### 方式一：命令行快速添加 (推荐 Claude Code 用户)\n如果您使用的是 Claude Code，可以直接运行：\n```bash\nclaude mcp add pdf-reader -- npx @sylphx\u002Fpdf-reader-mcp\n```\n\n### 方式二：配置文件手动添加 (Claude Desktop \u002F Windsurf \u002F Cline)\n找到对应系统的配置文件 `claude_desktop_config.json` (或 MCP 配置文件)，添加以下配置：\n\n**配置文件路径参考：**\n*   **macOS**: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n*   **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n*   **Linux**: `~\u002F.config\u002FClaude\u002Fclaude_desktop_config.json`\n\n**配置内容：**\n```json\n{\n  \"mcpServers\": {\n    \"pdf-reader\": {\n      \"command\": \"npx\",\n      \"args\": [\"@sylphx\u002Fpdf-reader-mcp\"]\n    }\n  }\n}\n```\n\n### 方式三：Cursor 编辑器\n1. 打开 **Settings** → **MCP** → **Add new MCP Server**。\n2. 类型选择 **Command**。\n3. 输入命令：`npx @sylphx\u002Fpdf-reader-mcp`。\n\n### 方式四：VS Code\n在终端运行以下命令直接添加：\n```bash\ncode --add-mcp '{\"name\":\"pdf-reader\",\"command\":\"npx\",\"args\":[\"@sylphx\u002Fpdf-reader-mcp\"]}'\n```\n\n## 基本使用\n\n配置完成后，重启您的 AI 客户端。您可以在对话中直接请求 AI 读取 PDF 文件，或者通过结构化参数调用 `read_pdf` 工具。\n\n### 最简单的使用示例\n\n直接向 AI 发送自然语言指令，例如：\n> \"请读取当前目录下的 `report.pdf` 文件并总结主要内容。\"\n\nAI 将自动调用 MCP 工具，返回包含全文、元数据和页码的结构化信息。\n\n### 高级用法示例 (结构化参数)\n\n如果您需要更精细的控制（如提取特定页面、图片或元数据），可以使用以下 JSON 格式的参数：\n\n**1. 提取全文与元数据**\n```json\n{\n  \"sources\": [{\n    \"path\": \"documents\u002Freport.pdf\"\n  }],\n  \"include_full_text\": true,\n  \"include_metadata\": true,\n  \"include_page_count\": true\n}\n```\n\n**2. 提取指定页面范围**\n支持灵活的页码格式（如 `\"1-5,10,15-20\"`）：\n```json\n{\n  \"sources\": [{\n    \"path\": \"documents\u002Fmanual.pdf\",\n    \"pages\": \"1-5,10\"\n  }],\n  \"include_full_text\": true\n}\n```\n\n**3. 支持绝对路径与远程 URL (v1.3.0+)**\n不再受限于相对路径，支持 Windows\u002FUnix 绝对路径及 HTTP 链接：\n```json\n{\n  \"sources\": [\n    { \"path\": \"C:\\\\Users\\\\John\\\\Documents\\\\contract.pdf\" }, \n    { \"url\": \"https:\u002F\u002Farxiv.org\u002Fpdf\u002F2301.00001.pdf\" }\n  ],\n  \"include_full_text\": true\n}\n```\n\n**4. 提取图片并保持自然阅读顺序**\n开启 `include_images` 后，工具会按 Y 轴坐标排序返回文本和图片，保持文档原始布局逻辑：\n```json\n{\n  \"sources\": [{ \"path\": \"presentation.pdf\" }],\n  \"include_images\": true,\n  \"include_full_text\": true\n}\n```\n\n### 核心特性提示\n*   **并行处理**: 多页或多文件处理时自动并行，大幅提升速度。\n*   **智能排序**: 基于 Y 坐标的内容排序，确保 AI 理解正确的阅读流（标题->图片->正文）。\n*   **容错性**: 单个页面解析失败不会影响整个文档的处理。","某法律科技团队的 AI 助手需要每天自动审查数百页的并购合同 PDF，从中提取关键条款并生成摘要报告。\n\n### 没有 pdf-reader-mcp 时\n- **处理速度极慢**：传统工具逐页顺序解析，处理一份 50 页的合同需耗时约 10 秒，面对批量任务时队列严重积压。\n- **内容逻辑错乱**：提取的文本常因 PDF 排版问题导致段落顺序颠倒（如脚注插入正文中间），AI 难以理解上下文逻辑。\n- **系统稳定性差**：一旦遇到某个损坏或加密的页面，整个解析进程直接崩溃，导致整批任务失败。\n- **环境兼容困难**：在 Windows 和 Linux 混合部署的开发环境中，文件路径格式差异常引发读取错误，调试成本高。\n\n### 使用 pdf-reader-mcp 后\n- **效率提升 10 倍**：利用多核并行处理技术，50 页文档的解析时间缩短至 1 秒左右，批量任务实现秒级响应。\n- **还原真实布局**：基于 Y 轴坐标智能排序内容，完美保留合同条款的原始阅读顺序，大幅提升了 AI 摘要的准确率。\n- **故障隔离稳健**：具备单页错误容错机制，即使个别页面解析失败，也能跳过错误继续处理剩余部分，确保任务不中断。\n- **跨平台无缝运行**：原生支持绝对与相对路径，自动适配 Windows\u002FUnix 系统差异，开发人员无需再为路径问题编写额外代码。\n\npdf-reader-mcp 将原本耗时且不稳定的 PDF 数据清洗工作，转变为高吞吐、高可靠的自动化流程，让 AI 代理真正具备了企业级的文档处理能力。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FSylphxAI_pdf-reader-mcp_4ee591a4.png","SylphxAI","Sylphx","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FSylphxAI_067ede4d.jpg","AI Platform as a Service. 19 production services, one SDK. We run everything on our own platform.",null,"hi@sylphx.com","https:\u002F\u002Fsylphx.com","https:\u002F\u002Fgithub.com\u002FSylphxAI",[81,85],{"name":82,"color":83,"percentage":84},"TypeScript","#3178c6",98.7,{"name":86,"color":87,"percentage":88},"JavaScript","#f1e05a",1.3,634,62,"2026-04-10T09:49:50","MIT","Linux, macOS, Windows","未说明",{"notes":96,"python":94,"dependencies":97},"该工具是基于 Node.js 的 MCP 服务器，无需 Python 环境。主要通过 npx 或 npm 安装运行。支持绝对路径和相对路径（v1.3.0+），可利用多核 CPU 进行并行处理以提升性能。配置时需根据使用的客户端（如 Claude Desktop, VS Code, Cursor 等）在相应的 JSON 配置文件中添加启动命令。",[98,99],"Node.js (隐含，因使用 npx\u002Fnpm)","TypeScript 5.0+",[13,35],[102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117],"ai-agent","llm-tool","mcp","model-content-protocol","nodejs","pdf","pdf-parse","pdf-parser","pdf-reader","stdio","typescript","ai-tools","document-processing","performance","model-context-protocol","parallel-processing","2026-03-27T02:49:30.150509","2026-04-11T00:44:49.073290",[121,126,131,136,141,146],{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},28526,"为什么使用绝对路径（如 C:\\Users\\...）时会报错'MCP error -32602: Absolute paths are not allowed'？","该问题已在 v1.3.0 版本中修复，现在完全支持绝对路径和相对路径。\n\n解决方法：\n1. 升级到最新版本：\n   - 使用 npm: `npm update @sylphx\u002Fpdf-reader-mcp`\n   - 使用 pnpm: `pnpm update @sylphx\u002Fpdf-reader-mcp`\n   - 直接使用最新版的 npx: `npx @sylphx\u002Fpdf-reader-mcp@latest`\n2. 升级后请完全重启你的 MCP 客户端（不仅仅是重新加载）。\n3. 现在可以直接在配置中使用绝对路径，例如：\n```json\n{\n  \"sources\": [{\"path\": \"C:\\\\Users\\\\SANDBOX\\\\Desktop\\\\sample-2.pdf\"}],\n  \"include_full_text\": true,\n  \"include_metadata\": true\n}\n```\n支持 Windows (C:\\...)、Unix\u002FMac (\u002Fhome\u002F...) 以及混合斜杠格式。","https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fissues\u002F136",{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},28527,"在 VSCode 中启动 MCP 服务器时遇到'SyntaxError: ... does not provide an export named router'错误怎么办？","这通常是由于缓存了旧版本的依赖包导致的。该问题已在 `@sylphx\u002Fmcp-server-sdk` v2.1.0 中修复。\n\n请按以下步骤解决：\n1. 彻底清理 npm 缓存：\n   ```bash\n   npm cache clean --force\n   ```\n2. 删除 npx 缓存目录：\n   - macOS\u002FLinux: `rm -rf ~\u002F.npm\u002F_npx`\n   - Windows: `rmdir \u002Fs \u002Fq %LOCALAPPDATA%\\npm-cache\\_npx`\n3. 验证当前最新版本号：\n   ```bash\n   npm view @sylphx\u002Fpdf-reader-mcp version\n   # 应显示 2.0.8 或更高\n   ```\n4. 指定版本运行测试：\n   ```bash\n   npx @sylphx\u002Fpdf-reader-mcp@2.0.8\n   ```\n如果问题依旧，请检查 Node.js 和 npm 版本并提供相关日志。","https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fissues\u002F240",{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},28528,"安装后 MCP 服务器显示没有工具（no tools）可用，如何解决？","此问题是由 SDK 中的一个 Bug 引起的，导致 `tools\u002Flist` 返回了错误的响应格式。该问题已在 v2.0.2 版本中修复。\n\n解决方法：\n1. 清理缓存以确保获取最新版本：\n   ```bash\n   npm cache clean --force\n   rm -rf ~\u002F.npm\u002F_npx\n   ```\n2. 重新安装或更新包到最新版。\n3. 重启 MCP 服务器。\n如果更新后问题仍然存在，请检查配置文件内容、Node 版本以及服务器日志中的具体错误信息。","https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fissues\u002F186",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},28529,"本地构建项目时报错'Property 'getAll' does not exist on type 'Metadata''怎么办？","这是一个类型定义问题，已在 PR #146 中修复。新的实现增加了对 `.getAll()` 方法的健壮性检查和回退机制。\n\n如果你无法立即更新代码库，可以手动应用以下逻辑修复 `src\u002Fhandlers\u002FreadPdf.ts`:\n```typescript\nif (typeof (metadataObj as unknown as { getAll?: () => unknown }).getAll === 'function') {\n  output.metadata = (metadataObj as unknown as { getAll: () => PdfMetadata }).getAll();\n} else {\n  \u002F\u002F 针对真实 PDF.js 元数据的回退方案\n  const metadataRecord: PdfMetadata = {};\n  for (const key in metadataObj) {\n    if (Object.prototype.hasOwnProperty.call(metadataObj, key)) {\n      metadataRecord[key] = (metadataObj as unknown as Record\u003Cstring, unknown>)[key];\n    }\n  }\n  output.metadata = metadataRecord;\n}\n```\n建议直接更新到包含此修复的最新版本以避免此类编译错误。","https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fissues\u002F64",{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},28530,"该工具是否支持从 PDF 中提取图片？","是的，从 v1.1.0 开始已完整支持图片提取功能。\n\n主要特性包括：\n1. **图片提取**：将嵌入的图片提取为 base64 编码数据，支持 RGB、RGBA 和灰度格式，兼容 JPEG、PNG 等格式，并返回宽度、高度、格式和页码等元数据。\n2. **内容排序优化 (v1.2.0+)**：文本和图片按照文档中的实际顺序返回。基于 Y 坐标的排序保留了自然的阅读流，帮助 AI 模型更好地理解文本与图片之间的关系。\n\n你可以在请求参数中设置 `include_images: true` 来启用此功能。详细用法请参阅更新后的 README 文档。","https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fissues\u002F180",{"id":147,"question_zh":148,"answer_zh":149,"source_url":125},28531,"在 Windows 上配置 `cwd` (工作目录) 后，相对路径仍然报'File not found'错误怎么办？","如果在 `mcp.json` 中设置了 `cwd`（例如 `\"cwd\": \"E:\\\\my-try\\\\project\"`）但相对路径依然失效，可能是路径解析或重启未生效的问题。\n\n建议尝试以下方案：\n1. **优先使用绝对路径**：自 v1.3.0 起，工具已完美支持绝对路径，可直接使用 `C:\\Users\\...` 格式的完整路径，避免相对路径解析带来的不确定性。\n2. **检查路径分隔符**：在 Windows 的 JSON 配置文件中，确保路径中的反斜杠已正确转义（使用双反斜杠 `\\\\`）。\n3. **完全重启服务**：修改配置后，不仅要重载编辑器，必须完全重启 MCP 服务器进程以使新的 `cwd` 设置生效。\n4. **验证当前目录**：如果必须使用相对路径，请确认文件确实相对于配置的 `cwd` 存在。若问题持续，建议切换到绝对路径方案。",[151,156,161,166,171,176,181,186,191,196,201,206,211,216,221,226,231,236,241,246],{"id":152,"version":153,"summary_zh":154,"released_at":155},190659,"v2.3.0","## 2.3.0（2026-02-04）\n","2026-02-04T22:59:06",{"id":157,"version":158,"summary_zh":159,"released_at":160},190660,"v2.2.0","## 2.2.0（2026-01-28）\n","2026-01-28T11:50:03",{"id":162,"version":163,"summary_zh":164,"released_at":165},190661,"v2.1.0","## 2.1.0（2025-12-17）\n","2025-12-17T17:26:21",{"id":167,"version":168,"summary_zh":169,"released_at":170},190662,"v2.0.8","## 2.0.8 (2025-12-05)\n","2025-12-05T22:22:19",{"id":172,"version":173,"summary_zh":174,"released_at":175},190663,"v2.0.7","## 2.0.7 (2025-12-03)\n","2025-12-03T16:56:55",{"id":177,"version":178,"summary_zh":179,"released_at":180},190664,"v2.0.3","## 2.0.3 (2025-11-30)\n","2025-11-30T11:35:34",{"id":182,"version":183,"summary_zh":184,"released_at":185},190665,"v2.0.2","## 2.0.2（2025-11-27）\n","2025-11-27T22:40:57",{"id":187,"version":188,"summary_zh":189,"released_at":190},190666,"v2.0.1","## 2.0.1（2025-11-27）\n","2025-11-27T21:39:24",{"id":192,"version":193,"summary_zh":194,"released_at":195},190667,"v2.0.0","## 2.0.0（2025-11-27）\n","2025-11-27T16:24:42",{"id":197,"version":198,"summary_zh":199,"released_at":200},190668,"v1.4.0","### ✨ 功能\n\n- 将文档从 VitePress 迁移到 Leaf ([dd1d9ee](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002Fdd1d9ee9a3250a3de9f9e297535c3bbe8a8f6527))\n\n### 🐛 错误修复\n\n- **ci:** 在 prepare 脚本中为 lefthook 使用显式路径 ([40c3655](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F40c36554a8958ded046c54fbfaad208b8fbad719))\n- **security:** 替换 js-yaml 以修复漏洞 ([ce7acc8](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002Fce7acc808b2c174eea03c4ecc3de3699994d8133))\n- **ci:** 允许 Dependabot PR 使用不带 frozen-lockfile 的 bun install ([af10706](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002Faf107067d7dcb1851c82d97c6a6896275985e263))\n- 升级到 SDK 1.0.0 和 Zod 4，以支持正确的 JSON Schema ([e9e21d5](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002Fe9e21d57edcc2f3ec7e9c96fd9d6e5c062ab1fd0))\n- 改进图像提取超时处理 ([c9e6f55](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002Fc9e6f55c90230f2eb2ccc8148470b130bf80f9c1))\n- 重要的安全和性能改进 ([19c7451](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F19c74518fd4f39f2115a0aef9d64733bb26f60df))\n\n### ♻️ 重构\n\n- 从 @modelcontextprotocol\u002Fsdk 迁移到 @sylphx\u002Fmcp-server-sdk ([98efbbb](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F98efbbb1a304b6aa9e30dead35f0fa6379939546))\n- 添加结构化日志系统 ([a337d93](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002Fa337d93c35abe16b102632a3e9871a6f3a94bdc1))\n- 去重图像提取逻辑 ([2e6ef33](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F2e6ef33577b7dbf902f88d4ecd4f33e2d1386b89))\n- 实现正确的 PDF 文档资源清理 ([7893cf6](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F7893cf63b07f0013b4f89a7dab91df4e7a1988c3))\n\n### 📚 文档\n\n- 添加适用于 VS Code、Claude Code、Cursor、Windsurf、Cline、Warp 的安装指南 ([28a3bf1](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F28a3bf1ae0d02abfedbbd9e371952a974c3aae08))\n\n### 🔧 杂项任务\n\n- 升级 @sylphx\u002Fbump 到 v0.12.1 ([9c597fb](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F9c597fbd052fe2171760229a46f4e49550a7aecb))\n- 升级 @sylphx\u002Fdoctor 到 v1.23.3 和 @sylphx\u002Fbump 到 v0.10.2 ([ff6849e](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002Fff6849e7a49596da449baa7b5e14f9ecaeedf4af))\n- 升级 @sylphx\u002Fdoctor 到 v1.23.2 ([9ab92cf](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F9ab92cf15e43aed336c771140d2675aa1c96ef65))\n- 将工具链迁移到 @sylphx 生态系统 ([fc2471f](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002Ffc2471ff61dcac287ec6d27f7038fdaaa088a727))\n- 将所有包升级到最新版本 ([8b6730b](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F8b6730bd86fcb8d992200574bce66946bec00886))\n- 清理未使用的文件和文件夹 ([8834d09](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F8834d09e1000ff57bae530a5ed069cc3b50a7866))\n- 从 Vitest 迁移到 Bun 测试运行器 ([7382d1b](https:\u002F\u002Fgithub.com\u002FSylphxAI\u002Fpdf-reader-mcp\u002Fcommit\u002F7382d1b037805d0f47271676d71b","2025-11-27T14:59:52",{"id":202,"version":203,"summary_zh":204,"released_at":205},190669,"v1.3.2","### Patch Changes\n\n-   c97a5c0: Refactor CI workflows to use company release standard. Simplified CI workflow for validation only and enhanced release workflow with full configuration.\n","2025-11-23T14:11:08",{"id":207,"version":208,"summary_zh":209,"released_at":210},190670,"v1.2.0","## Features\n\n**Content Ordering**: Preserve exact text and image order based on Y-coordinates\n- Content items within each page are now sorted by their vertical position\n- Enables AI to see content in the same order as it appears in the PDF\n- Text and images are interleaved based on document layout\n- Example: page 1 [text, image, text, image, image, text]\n- Uses PDF.js transform matrices to extract Y-coordinates\n- Automatically groups text items on the same line\n- Returns ordered content parts for optimal AI consumption\n\n## Internal Changes\n\n- New `extractPageContent()` function combines text and image extraction with positioning\n- New `PageContentItem` interface tracks content type, position, and data\n- Handler updated to generate content parts in document-reading order\n- Improved error handling to return descriptive error messages as text content\n\n## Code Quality\n\n- All tests passing (91 tests)\n- Coverage maintained at 97.76% statements, 90.95% branches\n- TypeScript strict mode compliance\n- Zero linting errors\n\n## Install\n\n```bash\nnpm install -g @sylphx\u002Fpdf-reader-mcp\n# or\npnpm add -g @sylphx\u002Fpdf-reader-mcp\n```","2025-10-31T18:11:00",{"id":212,"version":213,"summary_zh":214,"released_at":215},190671,"v1.1.0","## 🎨 Version 1.1.0 - Image Extraction & Performance\n\nThis release adds image extraction capabilities and significant performance improvements.\n\n### 🆕 New Features\n\n#### 🖼️ Image Extraction from PDFs\n- Extract embedded images from PDF pages as base64-encoded data\n- Support for multiple image formats: RGB, RGBA, Grayscale\n- Compatible with JPEG, PNG, and other embedded image types\n- Images include metadata: page number, dimensions, format\n- Optional parameter `include_images` (default: false for backward compatibility)\n\n**Usage Example:**\n\\`\\`\\`json\n{\n  \"sources\": [{ \"path\": \"presentation.pdf\", \"pages\": [1, 2, 3] }],\n  \"include_images\": true,\n  \"include_full_text\": true\n}\n\\`\\`\\`\n\n**Content Parts Format:**\n- Part 1: JSON summary with results and image_info metadata\n- Parts 2+: Actual images in page order as separate content parts\n- AI vision models can now see both text and images from PDFs\n\n### ⚡ Performance Improvements\n\n#### Parallel Page Processing (5-10x Speedup)\n- Refactored text extraction to process all pages concurrently\n- Uses \\`Promise.all\\` for parallel execution\n- 10-page PDF: ~5-8x faster\n- 50-page PDF: ~10x faster\n\n### 🏗️ Architecture\n\n#### Deep Refactoring\n- Broke down monolithic 454-line handler into focused modules\n- **handlers\u002FreadPdf.ts**: 454 → 143 lines (-68%)\n- **NEW** 6 specialized modules with single responsibilities\n\n### 🧪 Testing\n\n- **91 tests** (+60 from v1.0.0, +193%)\n- **99.04%** statement coverage (+8.78%)\n- **92.3%** branch coverage (+13.66%)\n- **100%** function coverage\n\n### 📊 Install\n\n\\`\\`\\`bash\nnpm install @sylphx\u002Fpdf-reader-mcp@1.1.0\n# or\npnpm add @sylphx\u002Fpdf-reader-mcp@1.1.0\n\\`\\`\\`\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fsylphxltd\u002Fpdf-reader-mcp\u002Fcompare\u002Fv1.0.0...v1.1.0\n\n---\n\n**Made with ❤️ by [Sylphx](https:\u002F\u002Fsylphx.com)**","2025-10-31T16:08:44",{"id":217,"version":218,"summary_zh":219,"released_at":220},190672,"v1.0.0","## 🎉 Version 1.0.0 - Major Release\n\nThis is a major release with breaking changes due to rebranding and significant improvements.\n\n### ⚠️ BREAKING CHANGES\n\n- **Package renamed**: `@sylphlab\u002Fpdf-reader-mcp` → `@sylphx\u002Fpdf-reader-mcp`\n- **Organization rebranded**: Sylphlab → Sylphx\n- **Website updated**: sylphlab.ai → sylphx.com\n\n### 🚀 Major Features\n\n- ✅ **Migrated to Biome**: 50x faster linting and formatting with unified tooling\n- ✅ **Fixed critical bugs**: Buffer\u002FUint8Array compatibility for PDF.js v5.x\n- ✅ **Fixed schema validation**: Resolved \\`exclusiveMinimum\\` issue affecting Windsurf, Mistral API, and other tools\n- ✅ **Improved metadata extraction**: Robust fallback handling for PDF.js compatibility\n\n### 📦 Updates\n\n- ✅ **Updated all dependencies** to latest versions:\n  - @modelcontextprotocol\u002Fsdk: 1.8.0 → 1.20.2\n  - pdfjs-dist: 5.1.91 → 5.4.296\n  - All ESLint packages removed, replaced with Biome\n  - All GitHub Actions updated to latest versions\n\n### 🐛 Bug Fixes\n\n- Fix nested test case that was not running (31 tests now run vs 30 before)\n- Fix TypeScript exactOptionalPropertyTypes compatibility\n- Use node: protocol for Node.js imports\n- Replace isNaN with Number.isNaN for safer type checking\n- Replace delete operator with undefined assignment for better performance\n\n### 📚 Documentation\n\n- Comprehensive README revision with modern structure\n- Added troubleshooting section based on resolved issues\n- Clear security explanation (relative paths only)\n- Added migration guide\n\n### 🔧 Migration Guide\n\nTo migrate from @sylphlab\u002Fpdf-reader-mcp to @sylphx\u002Fpdf-reader-mcp:\n\n1. **Uninstall old package:**\n   \\`\\`\\`bash\n   npm uninstall @sylphlab\u002Fpdf-reader-mcp\n   \\`\\`\\`\n\n2. **Install new package:**\n   \\`\\`\\`bash\n   npm install @sylphx\u002Fpdf-reader-mcp\n   \\`\\`\\`\n\n3. **Update your MCP configuration** to use @sylphx\u002Fpdf-reader-mcp\n\n**All functionality remains the same. No code changes required.**\n\n### ✅ Testing\n\n- All 31 tests passing\n- Coverage: 90.35% statements, 79.38% branches, 100% functions\n\n### 🙏 Thanks\n\nThank you to all contributors and users who reported issues. This release addresses all major bugs and compatibility issues reported in the past months.\n\n---\n\n**Made with ❤️ by [Sylphx](https:\u002F\u002Fsylphx.com)**","2025-10-31T14:21:01",{"id":222,"version":223,"summary_zh":224,"released_at":225},190673,"v0.3.23","**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fsylphlab\u002Fpdf-reader-mcp\u002Fcompare\u002Fv0.3.22...v0.3.23","2025-04-07T02:33:45",{"id":227,"version":228,"summary_zh":229,"released_at":230},190674,"v0.3.22","**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fsylphlab\u002Fpdf-reader-mcp\u002Fcompare\u002Fv0.3.21...v0.3.22","2025-04-07T02:22:52",{"id":232,"version":233,"summary_zh":234,"released_at":235},190675,"v0.3.20","**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fsylphlab\u002Fpdf-reader-mcp\u002Fcompare\u002Fv0.3.19...v0.3.20","2025-04-07T02:13:13",{"id":237,"version":238,"summary_zh":239,"released_at":240},190676,"v0.3.19","**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fsylphlab\u002Fpdf-reader-mcp\u002Fcompare\u002Fv0.3.18...v0.3.19","2025-04-07T02:10:13",{"id":242,"version":243,"summary_zh":244,"released_at":245},190677,"v0.3.18","**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fsylphlab\u002Fpdf-reader-mcp\u002Fcompare\u002Fv0.3.17...v0.3.18","2025-04-07T02:05:36",{"id":247,"version":248,"summary_zh":249,"released_at":250},190678,"v0.3.17","**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fsylphlab\u002Fpdf-reader-mcp\u002Fcompare\u002Fv0.3.16...v0.3.17","2025-04-07T01:50:55"]