内容
```text
+--------------------------------------------------------------------------------+
| |
| __ __ ____ ____ ____ _ |
| | \/ |/ ___| _ \ | _ \ ___ ___ _ _ _ __ ___ | |_ ___ |
| | |\/| | | | |_) |_____| | | |/ _ \ / __| | | | '_ ` _ \ | __/ _ \ |
| | | | | |___| __/_____| |_| | (_) | (__| |_| | | | | | | | || __/ |
| |_| |_|\____|_| |____/ \___/ \___|\__,_|_| |_| |_| \__\___| |
| |
| ____ _ _ _ _ _ |
| |_ _|_ __ | |_ ___| | (_) __ _ ___ _ __ ___| | |
| | || '_ \ | __/ _ \ | | |/ _` |/ _ \ '_ \ / __| | |
| | || | | || || __/ | | | (_| | __/ | | | (__| | |
| |___|_| |_| \__\___|_|_|_|\__, |\___|_| |_|\___|_| |
| |___/ |
| |
| 文档智能服务器 | OCR | 分析 | 组织 |
| |
+--------------------------------------------------------------------------------+
```
# 文档智能服务器
**模型上下文协议服务器，具备高级批量处理和智能文档组织功能**
🎯 **为 [Perplexity Desktop](https://www.perplexity.ai/)、[Claude Desktop](https://claude.ai/download) 及其他兼容MCP的客户端而设计** – 为您的AI助手赋予企业级文档智能能力。
本MCP服务器通过AI客户端中的自然语言请求，分析和重命名、分类、组织文档。它会递归扫描文件夹，检测重复文件，从PDF、DOCX、Pages、图像和文本文件中提取元数据，并对扫描文档使用OCR。预览模式、备份、撤销支持、元数据导出和内存优化的批量处理使其适用于大型个人档案。结果是一个AI驱动的文档工作流，本地化、快速且可自动化。
[](https://github.com/modelcontextprotocol)
[](LICENSE)
[](https://github.com/AndreasDietzel/mcp-document-intelligence)
[](test-results.json)
[](README.md)
[](OCR-INTEGRATION.md)
[](https://www.perplexity.ai/)
[](https://claude.ai/)
---
## 🎯 功能
### 🔍 **v4.6 新增 - 自动OCR集成**
- **📸 自动OCR扫描PDF**: 在文本提取字符数少于50时自动切换到Tesseract OCR
- **🖼️ 图片支持**: 在所有工具中处理.jpg、.jpeg、.png文件并使用OCR
- **🇩🇪 德语支持**: 预配置德语支持（`-l deu`）
- **🏢 增强的实体检测**: 新增对Vodafone、Telekom、O2、DHL、Amazon的识别
- **📁 修复分类**: Vodafone → 11_Telekommunikation（不是保险！）
- **⚡ 优雅的故障转移**: pdftotext → OCR → 空字符串（每个文件30秒超时）
- **📋 更多文档类型**: 新增Rezept、Kündigung、Mahnungs模式
- **🌍 全档案扫描**: 新脚本分析693个文件，改进559个文件并使用OCR
- **📚 文档**: 完整的[OCR-INTEGRATION.md](OCR-INTEGRATION.md)指南
### ⚡ **v4.5 - 高级档案管理**
- **🧹 cleanup_old_structure**: 删除旧文件夹层次，整合为标准分类
- **📁 optimize_folder_structure**: 删除空文件夹，将单文件分类移动到99_Sonstiges
- **🤖 intelligent_rename**: PDF内容分析用于智能命名（提取公司、文档类型）
- **📋 move_loose_files**: 基于模式的松散文件分类
- **🎯 生产就绪**: 测试了2714个文件，完全自动化的工作流
- **📚 完整文档**: [PRODUCTION-SETUP.md](PRODUCTION-SETUP.md)和[TESTFALL-PERPLEXITY.md](TESTFALL-PERPLEXITY.md)
### ⚡ **v4.4 - 性能优化**
- **🎯 内存高效处理**: 基于生成器的文件扫描 - 无内存溢出
- **📊 批量处理**: 每批处理25个文件，自动暂停
- **🛡️ 安全限制**: 可配置的限制（500文件/年）防止系统崩溃
- **🧹 垃圾回收**: 批处理之间的显式内存清理
- **⏸️ 进步处理**: 支持暂停和恢复的架构
- **📈 减少内存占用**: 与以前的版本相比减少了90%
### 🤖 **v4.3 - 自主组织**
- **🔄 auto_organize_folder**: 自动分析和组织文件夹
- **📥 process_downloads**: 自动将下载的文件归档并检测分类
- **🧩 batch_organize_large**: 处理>100个文件，分段且支持恢复
- **📊 智能分类**: 自动检测10+分类（Finanzen、Gesundheit、Reisen等）
- **💾 状态持久性**: 从JSON状态文件恢复中断的操作
- **🎯 十年检测**: 自动路由到Achziger/Neunziger/Nuller/Zehner/Zwanziger
### v4.2 - 完整的PDF OCR支持
- **📄 扫描PDF智能**: 完整的OCR解决方案，用于基于图像的PDF
- **🤖 自动检测**: 从文本提取到OCR的智能故障转移（<50个字符触发OCR）
- **📊 质量指标**: OCR置信度和质量评估
- **⚡ 优化处理**: PDF.js渲染 + Tesseract OCR（最多5页）
- **🌍 德语模型**: 预配置用于本地文档
- **📜 Apache-2.0许可**: 无PDF.js许可问题（Mozilla）
### 🚀 v4.1 - 质量和性能增强
- **🧪 全面的测试**: 100个自动化测试用例，99%的通过率
- **📊 性能指标**: 实时处理统计和吞吐量报告
- **🔍 增强的验证**: 文件大小、文件名长度和类型验证
- **🌐 更好的编码检测**: 自动UTF-8/Latin-1切换并报告
- **⚡ 优化处理**: 平均<100ms/文件，批量<2000ms
- **🛡️ 强大的错误处理**: 结构化的错误和可行的建议
### 🚀 v4.0 - 企业功能
- **🔍 递归扫描**: 深度文件夹分析，最多10级
- **👥 重复检测**: 基于SHA256的文件重复检测
- **👁️ 预览模式**: 执行前进行模拟操作
- **⏮️ 备份和撤销**: 自动备份，一键恢复
- **📊 元数据导出**: 将分析结果导出为JSON/CSV
- **🎯 智能过滤**: 按文件类型和关键词过滤
- **📋 复制模式**: 复制文件而不是移动
- **⚙️ 可配置规则**: 自定义文件夹组织模式
- **🎨 OCR质量反馈**: 扫描文档的置信度评分
- **📈 详细统计**: 全面的操作摘要
### 📦 批量文档处理
- **文件夹扫描**: 递归分析整个文件夹
- **批量组织**: 自动重命名和移动多个文件
- **智能文件夹结构**: 自动生成有组织的层次结构
- **工作流自动化**: 扫描 → 分析 → 预览 → 组织 → 撤销
### 📄 多格式文档智能
- **文本提取**: 从PDF、DOCX、Pages、图像、TXT中提取文本
- **完整的PDF OCR**: PDF.js + Tesseract.js用于扫描PDF（自动故障转移）
- **OCR质量评分**: 所有OCR操作的置信度指标和质量评估
- **多编码支持**: 自动检测和处理UTF-8、Latin-1/ISO-8859-1
- **强大的解析**: 处理空字节、特殊字符和不寻常的文件名
- **智能文件名建议**: 自动提取：
- 扫描仪时间戳（保留现有的`2024-01-24_14-30-45`格式）
- 文档日期（DD.MM.YYYY，YYYY-MM-DD）
- 参考编号（Invoice#，Customer#，Order#，Contract#）
- 关键词（Invoice，Contract，公司名称）
---
## 🚀 快速入门
### 系统需求
对于完整的PDF-OCR支持，请安装以下系统工具：
```bash
# macOS (via Homebrew)
brew install tesseract tesseract-lang # OCR引擎，包含所有语言
brew install poppler # PDF渲染工具（pdftoppm）
```
### 先决条件
您需要以下AI桌面客户端之一：
- **[Perplexity Desktop App](https://www.perplexity.ai/)** （macOS/Windows）
- **[Claude Desktop App](https://claude.ai/download)** （macOS/Windows）
两者都支持模型上下文协议（MCP），用于通过自定义工具扩展AI功能。
### 安装
```bash
git clone https://github.com/AndreasDietzel/mcp-document-intelligence.git
cd mcp-document-intelligence
npm install
npm run build
```
### 配置
将以下内容添加到MCP客户端配置中：
**对于Perplexity Desktop：**
位置：`~/Library/Application Support/Perplexity/perplexity-config.json` （macOS）
```json
{
"mcpServers": {
"document-intelligence": {
"command": "node",
"args": ["/path/to/mcp-document-intelligence/build/index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
**对于Claude Desktop：**
位置：`~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）
```json
{
"mcpServers": {
"document-intelligence": {
"command": "node",
"args": ["/path/to/mcp-document-intelligence/build/index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
**重启AI客户端**更新配置后。
### MCP文件系统集成
该服务器与官方的[MCP文件系统服务器](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)配合使用最佳，提供文件浏览和管理功能，为您的AI助手提供支持。
**Perplexity/Claude推荐设置：**
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/your/documents"
]
},
"document-intelligence": {
"command": "node",
"args": ["/path/to/mcp-document-intelligence/build/index.js"]
}
}
}
```
配置好这两个服务器后，您可以：
1. **询问AI**在文件夹中查找文档（文件系统服务器）
2. **分析和组织**它们自动（文档智能服务器）
3. **完成工作流**由与Perplexity/Claude的自然对话处理
---
## 📋 可用工具
### `analyze_document`
分析单个文档并建议智能文件名。
**输入：**
```json
{
"filePath": "/path/to/document.pdf"
}
```
**输出示例：**
```json
{
"originalFilename": "20240124_143045_scan.pdf",
"suggestedFilename": "20240124_143045_RE-2024-1234_rechnung_telekom.pdf",
"documentDate": "24.01.2024",
"references": ["RE-2024-1234"],
"keywords": ["rechnung", "telekom"],
"scannerDatePreserved": true,
"textLength": 2450,
"preview": "Rechnung Nr. RE-2024-1234..."
}
```
### `analyze_folder` ✨ v4.0增强
分析文件夹中的所有文档（批量处理，递归扫描，重复检测和过滤）。
**输入：**
```json
{
"folderPath": "/path/to/folder",
"recursive": true,
"fileTypes": ["invoice", "contract"],
"keywords": ["telekom", "vodafone"]
}
```
**输出：**
```json
{
"folderPath": "/path/to/folder",
"totalFiles": 15,
"duplicateGroups": [
{
"hash": "abc123...",
"count": 3,
"files": ["doc1.pdf", "doc1_copy.pdf", "duplicate.pdf"]
}
],
"documents": [
{
"originalPath": "...",
"suggestedFilename": "...",
"ocrQuality": "good",
"confidence": 0.95,
"metadata": {...}
}
]
}
```
### `suggest_folder_structure` ✨ v3.0新增
建议基于分析的文档的智能文件夹组织。
**输入：**
```json
{
"documents": [ /* array from analyze_folder */ ]
}
```
### `auto_organize_folder` 🤖 v4.3新增
分析和自动组织文件夹 - 将分析和重命名/移动一步完成。
**输入：**
```json
{
"sourcePath": "/path/to/source",
"archivePath": "/path/to/archive",
"dryRun": false,
"createCategories": true,
"stateFile": "/tmp/state.json"
}
```
**输出：**
```json
{
"total": 150,
"processed": 147,
"moved": 145,
"categorized": {
"01_Finanzen": 45,
"03_Gesundheit": 12,
"06_Reisen": 23,
"99_Sonstiges": 65
},
"errors": [{"file": "...", "error": "..."}]
}
```
### `process_downloads` 📥 v4.3新增
扫描下载文件夹并自动将文档归档并检测年份和分类。
**输入：```json
{
"downloadsPath": "~/Downloads",
"archiveBasePath": "/path/to/archive",
"autoMove": false,
"maxFiles": 50
}
```
**输出：```json
{
"scanned": 23,
"suggestions": [
{
"from": "~/Downloads/Rechnung.pdf",
"to": "/archive/Zwanziger/2025/01_Finanzen/2025-03-15_Rechnung_Telekom.pdf",
"year": 2025,
"category": "Finanzen"
}
],
"filed": [],
"errors": []
}
```
### `batch_organize_large` 🧩 v4.3新增
处理大型文件夹（>100个文件），分段且支持恢复。
**输入：```json
{
"folderPath": "/path/to/large/folder",
"targetArchivePath": "/path/to/archive",
"chunkSize": 50,
"stateFilePath": "/tmp/batch-state.json"
}
```
**输出：```json
{
"chunkCompleted": true,
"totalFiles": 500,
"processedFiles": 50,
"successCount": 48,
"errorCount": 2,
"percentComplete": 10,
"nextChunkExists": true,
"stateFilePath": "/tmp/batch-state.json"
}
```
### `batch_organize` ✨ v4.0增强
执行批量重命名和移动/复制文件并自动备份。
**输入：```json
{
"baseFolder": "/path/to/organized",
"mode": "move",
"createBackup": true,
"operations": [
{
"originalPath": "/path/scan001.pdf",
"targetFolder": "2024/Rechnungen/Telekom",
"newFilename": "2024-01-24_RE-123_rechnung_telekom.pdf"
}
]
}
```
**输出：```json"
]
}
```
**输出：```json
{
"success": true,
"mode": "move",
"filesProcessed": 15,
"filesFailed": 0,
"foldersCreated": 5,
"backupCreated": true,
"backupPath": "/path/.backup_2024-01-24T10-30-00.json",
"results": [...]
}
```
### `preview_organization` ✨ v4.0新增
模拟无实际更改的运行预览。
**输入：```json
{
"baseFolder": "/path/to/organized",
"operations": [ /* same as batch_organize */ ]
}
```
**输出：```json
{
"preview": [
{
"action": "move",
"from": "/path/scan001.pdf",
"to": "/path/organized/2024/Rechnungen/Telekom/2024-01-24_RE-123.pdf",
"status": "ok"
}
],
"warnings": [],
"stats": {
"totalFiles": 15,
"foldersToCreate": ["2024/Rechnungen/Telekom"],
"conflicts": 0,
"missingFiles": 0
},
"safeToExecute": true
}
```
### `undo_last_organization` ✨ v4.0新增
从自动备份恢复上一次组织操作。
**输入：```json
{
"baseFolder": "/path/to/organized"
}
```
**输出：```json
{
"success": true,
"restored": 15,
"failed": 0,
"backupFile": "/path/.backup_2024-01-24T10-30-00.json"
}
```
### `export_metadata` ✨ v4.0新增
将分析的文档元数据导出为JSON或CSV格式。
**输入：```json
{
"documents": [ /* array from analyze_folder */ ],
"format": "csv"
}
```
**输出（CSV）：```csv
Filename,Path,Date,References,Keywords,OCR Quality,Confidence,Type
scan001.pdf,/path/scan001.pdf,24.01.2024,RE-2024-1234,rechnung;telekom,good,0.95,invoice
...
```
---
## 🔧 使用案例
### 单个文档分析
```
analyze_document with filePath: "/path/to/scanned_invoice.pdf"
```
→ 提取发票号码、日期、公司名称并建议：
`2024-01-24_INV-2024-001_rechnung_telekom.pdf`
```
### 高级批量组织（v4.0）
**与Perplexity或Claude的示例对话：**
```
你： "分析我2026文件夹中的所有文档，递归查找重复文件"
AI（使用analyze_folder，递归=true）：
→ 扫描深度为10级
→ 找到150个文档
→ 检测到12个重复文件（3组）
→ 提取：日期、发票号码、公司
→ OCR质量：95%置信度平均值
AI（使用suggest_folder_structure）：
→ 建议：2026/Rechnungen/Telekom，2026/Vertraege/Vodafone等
→ 显示：文件重命名和目标文件夹的完整列表
AI（使用preview_organization）：
→ 预览：150个文件将被移动
→ 将创建的文件夹：8
→ 冲突：0
→ 安全执行：是
AI: "我找到了150个文档（12个重复文件）。是否将它们组织到2026/Rechnungen、2026/Vertraege，并使用智能文件名？"
你： "是，但复制而不是移动"
AI（使用batch_organize，模式="复制"，创建备份=true）：
→ 复制所有文件（保留原件）
→ 创建文件夹结构
→ 创建备份以备撤销
→ 自动处理所有内容
AI: "完成！已组织150个文档，创建了8个文件夹，备份已保存。15个文件已处理，0个失败。输入'undo'以撤销。"
你： "将元数据导出为CSV"
AI（使用export_metadata，格式="csv"）：
→ 导出所有文档元数据
→ 包括：文件名、日期、引用、关键词、OCR质量
AI: "已导出包含150个文档所有元数据的CSV文件。"
```
**完整工作流程v4.0：**
1. 扫描仪保存到"收件箱"文件夹
2. 告诉Perplexity/Claude递归分析+查找重复文件
3. 执行前预览更改
4. 使用复制或移动模式确认
5. 文件自动组织，自动备份
6. 导出记录元数据
7. 需要时随时撤销
### 工作流程自动化
- **之前**：手动排序100+扫描文档
- **之后**：一键→预览→秒级组织
- **安全性**：自动备份、预览模式、撤销功能
- **完美适用于**：税务文件、发票、合同、收据、档案
---
## 🛠️ 技术细节
### 依赖项
- **pdf-parse**：PDF文本提取
- **mammoth**：DOCX文档处理
- **adm-zip**：Pages文档提取
- **tesseract.js**：扫描文档和图像的OCR
- **@modelcontextprotocol/sdk**：MCP协议实现
### 文件结构
```
mcp-document-intelligence/
├── src/
│ └── index.ts # 主要服务器实现
├── build/ # 编译输出
├── package.json
├── tsconfig.json
└── README.md
```
### 文件名模式识别
分析器识别：
- **扫描仪时间戳**：`YYYY-MM-DD_HH-MM-SS` 或 `YYYYMMDD_HHMMSS`
- **文档日期**：`DD.MM.YYYY`，`YYYY-MM-DD`
- **引用模式**：
- `Rechnungs-Nr: XXX` / `发票：XXX`
- `Kunden-Nr: XXX` / `客户：XXX`
- `Bestell-Nr: XXX` / `订单：XXX`
- `Vertrag-Nr: XXX` / `合同：XXX`
- **关键词**：发票、合同、报价、订单、常见公司名称
### 文件夹结构生成
自动按以下方式对文档进行分组：
- **年份**：从文档日期中提取
- **类别**：Rechnungen、Verträge、Angebote、Mahnungen等
- **公司**：Telekom、Vodafone、Amazon、PayPal、银行等
---
## 🔒 隐私与安全
- ✅ **所有数据保持本地** - 个人数据无外部API调用
- ✅ **设备上OCR处理** - Tesseract.js本地运行
- ✅ **无数据传输** - 所有处理本地进行
- ✅ **无文档内容日志记录**
---
## 🌍 编码与国际支持
- ✅ **自动编码检测** - UTF-8和Latin-1/ISO-8859-1
- ✅ **国际字符** - 完整Unicode支持（日本語，中文，عربية，עברית）
- ✅ **德语变音符号** - 原生支持äöüÄÖÜß
- ✅ **特殊字符** - 处理文件名中的管道、冒号、引号
- ✅ **空字节处理** - 自动清理损坏的文件
- ✅ **编码信息** - 在分析结果中报告检测到的编码
---
## 🧪 质量保证
本项目通过全面测试维护高质量标准：
- **100个自动化测试**，涵盖所有功能
- **99%测试通过率**（99/100测试通过）
- **ISO 25010合规** - 验证质量特性
- **性能基准** - <100ms每文件平均值
- **安全测试** - 路径遍历和数据隐私验证
参见 [TEST-DOCUMENTATION.md](TEST-DOCUMENTATION.md) 获取详细测试覆盖和结果。
---
## 🚀 路线图
- [x] 多格式文档支持（PDF、DOCX、Pages、图像、TXT）
- [x] 批量处理支持
- [x] 基于内容的自动归档到文件夹
- [x] 递归文件夹扫描
- [x] 使用SHA256的重复文件检测
- [x] 预览模式（干预运行）
- [x] 备份和撤销功能
- [x] 元数据导出（JSON/CSV）
- [x] 复制与移动模式
- [x] OCR质量反馈
- [ ] 可配置的命名模板
- [ ] 自定义引用编号模式
- [ ] Excel/CSV文档支持
- [ ] 与文档管理系统集成
- [ ] 用于改进分类的机器学习
---
## 📄 许可证
MIT许可证 - 请参阅 [LICENSE](LICENSE) 文件
---
## 🙏 致谢
- 使用 [Model Context Protocol SDK](https://github.com/modelcontextprotocol) 构建
- 概念灵感来自并基于 [MCP Filesystem Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)
- PDF解析由 [pdf-parse](https://www.npmjs.com/package/pdf-parse) 提供
- OCR由 [Tesseract.js](https://tesseract.projectnaptha.com/) 提供
---
**为智能文档工作流而打造** 📄✨
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器