Document Reader MCP Server

# 文档阅读器 MCP 服务器 一个支持多种文档格式的 Model Context Protocol (MCP) 服务器，可以读取 Word、PDF、文本文件、RTF 等格式，并提供图片提取与分析功能。 ## 🚀 快速开始 ### 1. 安装依赖 ```bash # 方式1：使用安装脚本（推荐） python install_deps.py # 方式2：手动安装 pip install -r requirements.txt ``` ### 2. 启动服务器 ```bash python server.py ``` ### 3. 配置 Kiro IDE 在 Kiro IDE 中创建或编辑 `.kiro/settings/mcp.json` 文件： **方式1：简化配置（推荐）** ```json { "mcpServers": { "document-reader": { "command": "python", "args": ["server.py"], "cwd": "D:\\your-path\\document-reader-mcp", "env": { "PYTHONIOENCODING": "utf-8" }, "disabled": false, "autoApprove": [ "list_supported_formats", "get_document_info", "read_document", "read_document_with_media" ] } } } ``` **方式2：完整路径配置** ```json { "mcpServers": { "document-reader": { "command": "python", "args": ["D:\\devolp\\code1\\document-reader-mcp-master\\document-reader-mcp\\server.py"], "cwd": "D:\\devolp\\code1\\document-reader-mcp-master\\document-reader-mcp", "env": { "PYTHONPATH": "D:\\devolp\\code1\\document-reader-mcp-master\\document-reader-mcp", "PYTHONIOENCODING": "utf-8" }, "disabled": false, "autoApprove": [ "list_supported_formats", "get_document_info", "read_document", "read_document_with_media" ] } } } ``` **配置说明：** - `cwd`: 项目根目录路径 - `PYTHONPATH`: 确保模块导入正常（方式2需要） - `PYTHONIOENCODING`: 确保中文字符正确显示 - `autoApprove`: 自动批准的安全工具列表，减少确认步骤 ### 4. 测试功能 ```bash # 测试图表分析 python simple_diagram_reader.py # 测试核心功能 python test_core_features.py ``` ## ✨ 核心功能 - **多格式文档读取**: 支持 Word (.docx)、PDF、Excel (.xlsx/.xls)、文本文件、RTF 等格式 - **图片提取与分析**: 自动提取文档中的图片并进行结构分析 - **图表内容理解**: 基于 OpenCV 分析流程图、架构图等技术图表 - **媒体信息提取**: 提取文档中的图片和链接信息 - **链接验证**: 自动检查文档中链接的有效性 - **页面范围选择**: PDF 文档支持指定页面范围读取 ## 🛠️ MCP 工具 ### `read_document_ 增强阅读文档，同时提取文字和图片内容 - `file_path`: 文 息 ### `extract_documen` 提取文档中的图片和链接 - `file_path`: 文档路径 - `save_images`: 是否保存图片到本地 ### ` 无需复杂配置 - `image_path`: 图片路径 ## 📊 图表分析能力 - **结构识别**: 检测矩形、圆形、线条等形元素 - *构图、网络图等 特征 - **技术理解**: 基 ## 💡 使用场景 ### 增强文档阅读 ``` cx ``` 自动提取文字内容和所有图片，并进行结构分析。 ### 开发时 当 AI-Agent 需要理解业 ``` 文件夹 analyze_s") 结构 ``` ├── server.py 主程序 析核心模块 ├── ins 依赖安装脚本 ├hon 依赖列表 └── extracted_ima ``` ## 🔧 依赖说明 **核心依赖**: - `mcp`: MCP 协议框架 - `pytho - `PyPDF2`: PDF 文档处理 - `opencv-python`: 图像分析 - `numpy`: 数值计算 **可选依赖* - `st - ` ## 设计理念 这个项目专注于**实用性**和***： OCR 配置 - 基于图像结构分析理解图表 -传 - 为 AI-Agent 开发提供 ## 📄 许可证 MIT License: { "FASTMCP_LOG_LEVEL": "ERROR" }, "disabled": false, "autoApprove": ["list_supported_formats"] } } } ``` ### 配置说明 - `autoApprove`: 自动批准的安全工具列表 - `disabled`: 设为 `false` 启用服务器 - `cwd`: 工作目录（本地安装时需要） - `PYTHONIOENCODING`: 确保中文字符正确显示 ## 使用方法 ### 🚀 快速开始 1. **配置MCP服务器**（见上方配置说明） 2. **重启Kiro IDE** 或重新连接MCP服务器 3. **开始使用工具** ### 📖 基础文档阅读 #### 读取Word文档 ```json { "tool": "read_document", "arguments": { "file_path": "report.docx" } } ``` #### 读取PDF特定页面 ```json { "tool": "read_document", "arguments": { "file_path": "document.pdf", "page_range": "1-5" } } ``` #### 读取Excel文档 ```json { "tool": "read_document", "arguments": { "file_path": "data.xlsx" } } ``` #### 读取Excel特定工作表 ```json { "tool": "read_document", "arguments": { "file_path": "data.xlsx", "sheet_name": "Sheet1" } } ``` #### 获取文档信息 ```json { "tool": "get_document_info", "arguments": { "file_path": "example.docx" } } ``` ### 🖼️ 图片自动解析功能 #### 方式1：增强文档阅读（推荐） ```json { "tool": "read_document_with_media", "arguments": { "file_path": "document.docx", "include_media_info": true } } ``` **特点**： - ✅ 自动解析图片和链接 - 📊 在文档内容后显示媒体信息 - 🎯 适合完整文档分析 #### 方式2：专门媒体提取 ```json { "tool": "extract_document_media", "arguments": { "file_path": "document.docx", "extract_images": true, "extract_links": true, "save_images": false } } ``` **特点**： - 🎯 专门用于媒体分析 - 💾 可选择保存图片到本地 - 📈 提供详细统计信息 #### 方式3：普通阅读（不解析图片） ```json { "tool": "read_document", "arguments": { "file_path": "document.docx" } } ``` **特点**： - 🚀 速度最快 - 📝 只获取文本内容 - 🎯 适合纯文本需求 ### 🔍 图片解析能力展示 当使用图片解析功能时，你会得到： ``` 文档媒体信息 (example.docx): 摘要: - 图片总数: 2 - 链接总数: 3 - 图片处理错误: 0 - 链接处理错误: 0 图片信息: 1. image1.png - 格式: PNG - 尺寸: (670, 346) - 大小: 174900 字节 - 流程图分析: - 文本: 检测到的文字内容 - 节点数: 5 - 连线数: 4 2. chart.jpg - 格式: JPEG - 尺寸: (800, 600) - 大小: 245600 字节 链接信息: 1. https://www.example.com - 域名: www.example.com - 协议: https - 状态: 可访问 (HTTP 200) ``` ### 🛠️ 实用工具 #### 查看支持格式 ```json { "tool": "list_supported_formats", "arguments": {} } ``` #### 批量处理示例 ```python # 在Kiro中，你可以这样批量处理文档 documents = ["doc1.docx", "doc2.pdf", "doc3.txt"] for doc in documents: # 使用增强阅读获取完整信息 result = mcp_call("read_document_with_media", { "file_path": doc, "include_media_info": True }) print(f"处理完成: {doc}") ``` ## 页面范围格式 PDF文档支持灵活的页面范围选择： - `"all"` - 所有页面（默认） - `"1-5"` - 第1到5页 - `"1,3,5"` - 第1、3、5页 - `"1-3,7,10-12"` - 第1-3页、第7页、第10-12页 ## 错误处理 - 自动检测文本文件编码 (UTF-8, GBK, GB2312, Latin-1) - 优雅处理缺失的依赖库 - 详细的错误信息和建议 ## 媒体处理功能 🆕 ### 图片处理 - **支持格式**: Word文档中的嵌入图片 - **提取信息**: 文件名、格式、尺寸、大小 - **保存功能**: 可选择将图片保存到本地 - **错误处理**: 优雅处理损坏或不支持的图片 ### 链接处理 - **支持格式**: Word、PDF、文本文件中的HTTP/HTTPS链接 - **提取信息**: URL、域名、协议 - **有效性验证**: 自动检查链接是否可访问 - **状态码**: 显示HTTP响应状态码 ### 使用场景 - 文档内容分析和审计 - 媒体资源清单生成 - 链接有效性批量检查 - 文档迁移前的资源盘点 ## 在 Kiro IDE 中使用 ### 🎯 配置步骤 1. **打开Kiro IDE** 2. **创建MCP配置文件**： - 路径：`.kiro/settings/mcp.json` - 如果文件不存在，创建一个新文件 3. **添加配置内容**： ```json { "mcpServers": { "document-reader": { "command": "python", "args": ["server.py"], "cwd": "D:\\your-path\\document-reader-mcp", "env": { "PYTHONIOENCODING": "utf-8" }, "disabled": false, "autoApprove": [ "list_supported_formats", "get_document_info" ] } } } ``` 4. **重启Kiro** 或使用命令面板搜索 "MCP" 重新连接服务器 ### 💡 使用技巧 #### 在聊天中使用 ``` 请帮我读取这个Word文档的内容，并分析其中的图片信息： 文件路径：./reports/monthly-report.docx ``` Kiro会自动调用 `read_document_with_media` 工具。 #### 批量文档分析 ``` 请分析这个文件夹中所有Word文档的媒体信息： - ./docs/report1.docx - ./docs/report2.docx - ./docs/presentation.docx ``` #### 文档格式转换准备 ``` 我需要将这些PDF文档转换为Markdown， 请先帮我分析文档结构和媒体内容： ./pdfs/technical-guide.pdf ``` ### 🔧 故障排除 #### 常见问题 1. **MCP服务器连接失败** - 检查 `cwd` 路径是否正确 - 确认 `server.py` 文件存在 - 检查Python环境是否正确 2. **中文字符显示异常** - 确保配置中包含 `"PYTHONIOENCODING": "utf-8"` 3. **图片解析失败** - 检查是否安装了 `Pillow` 库：`pip install Pillow` - 确认Word文档中确实包含图片 4. **链接验证不工作** - 安装 `requests` 库：`pip install requests` - 检查网络连接 #### 调试方法 1. **查看MCP服务器状态** - 在Kiro中打开命令面板 - 搜索 "MCP Server" 查看连接状态 2. **测试基础功能** ```json { "tool": "list_supported_formats", "arguments": {} } ``` 3. **检查依赖库** ```json { "tool": "list_supported_formats", "arguments": {} } ``` 返回结果会显示各个依赖库的安装状态。 ## 性能与最佳实践 ### ⚡ 性能优化 #### 选择合适的工具 - **纯文本需求**：使用 `read_document`（最快） - **需要媒体信息**：使用 `read_document_with_media` - **专门媒体分析**：使用 `extract_document_media` #### 大文件处理 ```json { "tool": "read_document", "arguments": { "file_path": "large-document.pdf", "page_range": "1-10" } } ``` 对于大型PDF，使用页面范围限制可以显著提升性能。 #### 批量处理建议 - 避免同时处理过多大文件 - 优先处理小文件，再处理大文件 - 使用 `get_document_info` 先了解文件大小 ### 🎯 最佳实践 #### 1. 文档分析工作流 ``` 1. get_document_info - 了解文档基本信息 2. read_document - 快速获取文本内容 3. read_document_with_media - 深入分析（如需要） ``` #### 2. 媒体资源管理 ```json { "tool": "extract_document_media", "arguments": { "file_path": "document.docx", "extract_images": true, "extract_links": true, "save_images": true } } ``` 设置 `save_images: true` 可以将图片保存到本地，便于后续处理。 #### 3. 错误处理 - 始终检查返回结果中的错误信息 - 对于批量处理，建议逐个处理并记录失败的文件 - 使用 `list_supported_formats` 确认依赖库状态 ### 📊 性能数据 | 操作 | 平均耗时 | 内存使用 | |------|----------|----------| | 读取文本文件 (1MB) | < 0.1秒 | 低 | | 读取Word文档 (5MB) | < 0.5秒 | 中等 | | 读取PDF文档 (10MB) | < 1秒 | 中等 | | 图片提取 (含10张图) | < 2秒 | 较高 | | 链接验证 (10个链接) | 2-5秒 | 低 | ## 依赖库 ### 核心依赖 - `mcp` - MCP协议支持 - `python-docx` - Word文档处理 - `PyPDF2` - PDF文档处理 - `striprtf` - RTF文档处理 ### 媒体处理依赖 🆕 - `Pillow` - 图片处理和分析 - `requests` - 链接验证（可选） ### 安装命令 ```bash # 安装所有依赖 pip install -r requirements.txt # 或单独安装 pip install mcp python-docx PyPDF2 striprtf Pillow requests openpyxl pandas ``` ## 快速参考 ### 🔧 工具对比表 | 工具名称 | 读取文本 | 解析图片 | 提取链接 | 性能 | 适用场景 | |----------|----------|----------|----------|------|----------| | `read_document` | ✅ | ❌ | ❌ | 🚀🚀🚀 | 快速文本阅读 | | `read_document_with_media` | ✅ | ✅ | ✅ | 🚀🚀 | 完整文档分析 | | `extract_document_media` | ❌ | ✅ | ✅ | 🚀 | 专门媒体提取 | | `get_document_info` | ❌ | ❌ | ❌ | 🚀🚀🚀 | 文档信息查看 | | `list_supported_formats` | ❌ | ❌ | ❌ | 🚀🚀🚀 | 功能状态检查 | ### 📋 支持格式一览 | 格式 | 扩展名 | 文本读取 | 图片提取 | 链接提取 | 页面范围 | |------|--------|----------|----------|----------|----------| | Word文档 | .docx | ✅ | ✅ | ✅ | ❌ | | PDF文档 | .pdf | ✅ | ❌ | ✅ | ✅ | | Excel文档 | .xlsx, .xls | ✅ | ✅ | ✅ | ❌ | | 纯文本 | .txt, .md | ✅ | ❌ | ✅ | ❌ | | RTF文档 | .rtf | ✅ | ❌ | ❌ | ❌ | | 代码文件 | .py, .js, .html, .css | ✅ | ❌ | ✅ | ❌ | ### 🎯 使用场景推荐 | 场景 | 推荐工具 | 配置建议 | |------|----------|----------| | 快速浏览文档内容 | `read_document` | 无特殊配置 | | 文档内容+媒体分析 | `read_document_with_media` | `include_media_info: true` | | 媒体资源清单 | `extract_document_media` | `save_images: true` | | 链接有效性检查 | `extract_document_media` | 安装 `requests` 库 | | 大文件处理 | `read_document` | 使用 `page_range` | | 批量文档处理 | 组合使用 | 先用 `get_document_info` | ## 更新日志 ### v2.1.0 🆕 - ✅ 新增Excel文档支持 (.xlsx/.xls) - ✅ Excel图片提取功能 - ✅ Excel链接提取和验证功能 - ✅ Excel工作表信息获取 - ✅ 支持指定工作表读取 ### v2.0.0 - ✅ 新增图片自动解析功能 - ✅ 新增链接提取和验证功能 - ✅ 新增 `read_document_with_media` 工具 - ✅ 新增 `extract_document_media` 工具 - ✅ 支持图片保存到本地 - ✅ 支持流程图基础分析 - ✅ 完善错误处理机制 ### v1.0.0 - ✅ 基础文档读取功能 - ✅ 多格式支持 - ✅ PDF页面范围选择 - ✅ 文档信息获取 ## 许可证 MIT License