PDF文本提取MCP
使用本机C++绑定进行PDF文本提取的模型上下文协议服务器。
项目结构
pdf-text-mcp/
├── packages/
│ ├── pdf-parser/ # Native C++ addon + TypeScript wrapper
│ ├── mcp-server/ # MCP protocol server (dual transport: stdio/HTTP)
│ ├── pdf-mcp-client/ # Shared Python client library
│ ├── example-agent-stdio/ # stdio transport example (local MCP usage)
│ └── example-agent-http/ # HTTP transport example (token-efficient remote usage)
├── .claude-session-data.md # Claude context (development notes)
└── README.md # This file快速开始
先决条件
必修的：
- 仅仅 -命令运行器（安装：
cargo install just或通过包管理器） - Node.js>=18.0.0
- C++17编译器
- CMake>=3.15
- ICU图书馆
对于Python代理：
- Python>=3.10
- 紫外线 -Python包管理器
快速设置
# Check if all required tools are installed
just doctor
# Install dependencies for all packages
just install-all
# Build all packages
just build-all
# Run tests
just test-all运行演示
构建完成后，您可以运行示例AI代理来查看系统的运行情况。
选项1:stdio传输（本地，最简单）
cd packages/example-agent-stdio
just demo选项2:HTTP传输（远程服务器）
终端1-启动MCP服务器：
cd packages/mcp-server
TRANSPORT_MODE=http just run # Runs locally on port 3000终端2-运行代理：
cd packages/example-agent-http
just demo处理单个包
每个包都是独立的，有自己的 Justfile:
# Build specific package
cd packages/pdf-parser && just build
cd packages/mcp-server && just build
# Test specific package
cd packages/pdf-parser && just test
cd packages/mcp-server && just test
cd packages/example-agent-stdio && just test
cd packages/example-agent-http && just test
# See available commands for a package
cd packages/ && just --list有关详细的使用说明：
- MCP服务器设置：参见 软件包/mcp服务器/README.md
- PDF Parser API：参见 软件包/pdf解析器/README.md
- 共享客户端库：参见 软件包/pdf-mcp客户端/README.md
- stdio示例（本地）：参见 包/示例代理stdio/README.md
- HTTP示例（远程，令牌高效）：参见 包/示例代理http://README.md
可用命令
根级别命令 （方便）：
just help # Show all available commands
just list # List all packages
just doctor # Check if required tools are installed
just setup # Install dependencies and build everything
just build-all # Build all packages in dependency order
just test-all # Test all packages
just lint-all # Lint all packages
just format-all # Format all packages
just check-all # Run all checks (lint, format-check, type-check, test)
just clean-all # Clean all packages
just install-all # Install dependencies for all packages包级命令 （在包目录中运行）：
所有软件包中都有通用命令：
just build-构建包just test-运行测试just clean-清理构建工件just install-安装依赖项
每种包类型的附加命令：
- Node.js包 （pdf解析器、mcp服务器）：
dev,lint,format,test-watch,test-coverage,test-manual - Python包 （pdf mcp客户端，示例代理stdio，示例代理http）：
lint,format,type-check,check,test-verbose,test-coverage - 仅限mcp服务器：Docker和Kubernetes命令（请参阅mcp服务器README）
跑 just --list 在任何包内查看所有可用命令。
特性
- ✅ PDF文本提取（文件和缓冲区）
- ✅ 元数据提取（标题、作者、日期等）
- ✅ 自动RTL/LTR文本方向检测（希伯来语、阿拉伯语）
- ✅ MCP协议集成（stdio+HTTP传输）
- ✅ 用于远程服务器的令牌高效HTTP客户端
- ✅ 文件大小限制和超时保护
- ✅ 真正的异步取消，支持超时
- ✅ TypeScript+Python类型定义
- ✅ 综合测试套件（91项测试）
- ✅ 使用PydanticAI的AI代理示例
- ✅ Docker容器化和Kubernetes部署
- ✅ 可观测性（普罗米修斯、格拉法纳、洛基）
超出范围：
- ❌ 加密/密码保护的PDF
包裹
@pdf文本mcp/pdf解析器
TypeScript库封装了pdf文本提取C++库。
- 基于文件和缓冲区的提取
- 元数据抽取
- 原生C++性能
- 完全支持TypeScript
@pdf文本mcp/mcp服务器
MCP服务器通过JSON-RPC协议公开PDF提取。
- 双重运输：stdio（本地）和HTTP（远程）
extract_text和extract_metadata工具- Claude桌面集成
- Docker/Kubernetes已准备好健康探测
- 用于HTTP模式的API密钥验证
pdf mcp客户端
共享Python客户端库，用于令牌高效的PDF提取。
- 直接HTTP调用MCP服务器（绕过LLM-0令牌）
- Base64编码和协议助手
- 使用httpx的异步/等待API
- 44个单元测试，全覆盖
示例代理stdio
使用stdio传输的AI代理示例（本地子进程）。
- PydanticAI框架与谷歌Gemini
- MCP客户端通过stdio传输
- PDF摘要、文本提取、元数据分析
- 最适合：本地开发、Claude Desktop集成
代理http示例
使用HTTP传输的令牌高效AI代理（远程服务器）。
- 直接HTTP提取（使用了0个令牌）
- 仅将提取的文本发送到LLM（不是PDF）
- 与简单方法相比，代币成本降低了96%
- 最适合：生产、远程服务器、成本优化
建筑
该项目由多个协同工作的包组成：
┌─────────────────────────────────────┐
│ Claude Desktop / AI Client │
└──────────────┬──────────────────────┘
│ JSON-RPC over stdio/HTTP
┌──────────────▼──────────────────────┐
│ MCP Server │
│ - Protocol handling │
│ - extract_text tool │
│ - extract_metadata tool │
└──────────────┬──────────────────────┘
│
┌──────────────▼──────────────────────┐
│ @pdf-text-mcp/pdf-parser │
│ - TypeScript API │
│ - Native addon loading │
└──────────────┬──────────────────────┘
│
┌──────────────▼──────────────────────┐
│ pdf-text-extraction (C++) │
│ - PDF parsing │
│ - Text extraction with ICU bidi │
└─────────────────────────────────────┘设计模式
基于流的核心功能（DRY原理）:
- 核心功能与
IByteReaderWithPosition流 - 文件/缓冲区操作是创建适当流的精简包装器
- 提取逻辑的单一真实来源
工人架构:
ICancellable类型安全取消接口CancellableAsyncWorker模板基类- 专业基础课程：
TextExtractionBaseWorker,MetadataExtractionBaseWorker - 工作人员实施
native/workers/文件夹 - 客户端绑定(
napi_bindings,pdf_extractor_addon)根 - 用于在独立线程上进行非阻塞提取的N-API异步工作程序
- 用于立即清理资源的原子取消标志
发展
看 .claude-session-data.md 用于开发说明、决策和上下文。
每个包都有自己的README，其中包含详细的操作说明。
许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。