Pdf Extractor Server V2

PDFExtractor MCP服务器

概述

这 PDFExtractor 是一个模型上下文协议（MCP）服务器，它从位于指定位置的文件（如PDF、Word、Markdown）中提取内容 file-to-extract 目录，并使用Apache Tika将内容转换为HTML。它采用Spring Boot、Jetty和MCP SDK构建，支持HTTP/SSE和STDIO传输协议，使其与Claude Desktop或MCP Inspector等MCP兼容客户端兼容。服务器公开了一个工具， extract-file-to-html，它接受文件名并以HTML格式返回提取的内容以及元数据。

该项目专为需要自动提取文件内容并将其转换为HTML的开发人员和系统而设计，适用于文档处理、内容管理或与AI助手集成等应用程序。

特性

• 文件内容提取：使用Apache Tika从各种文件格式（PDF、DOCX、Markdown等）中提取文本和元数据。
• HTML转换：使用Tika将提取的内容转换为HTML ToHTMLContentHandler.
• MCP兼容性：使用同步工具支持MCP协议(extract-file-to-html)用于与MCP兼容的客户端集成。
• 运输选项：支持HTTP/SSE（端口45452）和STDIO传输，以实现灵活集成。
• REST端点：提供 /api/test-extract 用于通过HTTP POST测试文件提取的端点。
• 健康检查：包括a /api/health 端点以验证服务器状态。
• CORS支持：允许对测试端点进行跨源请求，从而促进基于web的测试。
• 可配置目录：从可配置文件读取文件 file-to-extract 目录，指定于 application.properties.

先决条件

• Java：版本21或更高版本。
• 梅文：用于构建项目的3.6.0或更高版本。
• 支持的文件格式：确保文件在 file-to-extract 目录采用Apache Tika支持的格式（例如PDF、DOCX、TXT、Markdown）。

安装

1. 克隆存储库:

   git clone https://github.com/RayenMalouche/MCP-PDF-Extractor-server-v2.git
   cd MCP-PDF-Extractor-server-v2

1. 创建文件目录:

- 服务器从中读取文件 file-to-extract 默认情况下为目录，如中所指定 application.properties. - 在项目根目录中创建此目录：

     mkdir file-to-extract

- 将要提取的文件（例如PDF、Word文档）放置在此目录中。

1. 构建项目:

- 使用Maven构建项目：

     mvn clean install

配置

服务器配置在中定义 src/main/resources/application.properties:

spring.application.name=FileExtractMcpServer
file.directory=file-to-extract

• spring.application.name：应用程序的名称。
• file.directory：存储输入文件的目录（默认： file-to-extract).如果需要，更新此属性以更改目录路径。

运行服务器

服务器可以在两种模式下运行：HTTP/SSE或STDIO。

1. HTTP/SSE模式

• 默认模式，适用于基于web或MCP Inspector的集成。
• 运行服务器：

  mvn spring-boot:run

• 对于可流式传输的HTTP（MCP检查器兼容性）：

  mvn spring-boot:run -- --streamable-http

• 服务器启动于 http://localhost:45452 具有以下端点：

- MCP端点: http://localhost:45452/ （或 /message 用于流式传输HTTP）。 - SSE 终端: http://localhost:45452/sse. - 测试终点: http://localhost:45452/api/test-extract （POST）。 - 健康检查: http://localhost:45452/api/health （获取/发布）。

2. STDIO模式

• 适用于命令行或本地MCP客户端集成。
• 运行服务器：

  mvn spring-boot:run -- --stdio

示例用法

使用MCP工具

• 这 extract-file-to-html 该工具接受带有 filename 现场。
• 示例请求（通过MCP客户端或HTTP POST发送到 /api/test-extract):

  {
    "filename": "example.pdf"
  }

• 示例使用 curl:

  curl -X POST http://localhost:45452/api/test-extract \
       -H "Content-Type: application/json" \
       -d '{"filename":"example.pdf"}'

• 预期响应：

  {
    "status": "success",
    "message": "File content extracted successfully",
    "html": "...",
    "metadata": {
      "filename": "example.pdf",
      "contentType": "application/pdf"
    }
  }

• 如果找不到文件或提取失败，则返回错误响应：

  {
    "status": "error",
    "message": "Failed to extract file: File not found",
    "errorType": "IOException"
  }

健康检查

• 验证服务器状态：

  curl http://localhost:45452/api/health

• 答复：

  {
    "status": "healthy",
    "server": "File Extract MCP Server",
    "version": "1.0.0"
  }

项目结构

PDFExtractor/
├── src/
│   ├── main/
│   │   ├── java/com/mcp/RayenMalouche/pdf/v2/PDFExtractor/
│   │   │   ├── PdfExtractorApplication.java  # Main application with MCP server logic
│   │   │   ├── config/
│   │   │   │   ├── ConfigLoader.java        # Loads configuration from application.properties
│   │   ├── resources/
│   │   │   ├── application.properties        # Configuration file
│   ├── test/                                # Test sources (not included in this setup)
├── file-to-extract/                         # Directory for input files
├── pom.xml                                  # Maven configuration
├── README.md                                # This file

依赖项

• Spring Boot：构建应用程序的框架(spring-boot-starter, spring-boot-starter-web).
• 只有 Apache：用于文件解析和HTML转换(tika-core, tika-parsers-standard-package).
• MCP-SDK：用于MCP协议支持(io.modelcontextprotocol.sdk:mcp).
• 喷气：用于HTTP/SSE传输的嵌入式服务器(jetty-server, jetty-ee10-servlet).
• 杰克逊：JSON处理(jackson-databind).

局限性

• 图像处理：文档中的嵌入式图像（例如DOCX或PDF）在HTML输出中引用（例如。， src="embedded:image1.jpeg")但不直接供应。需要额外的逻辑来提取和提供图像（请参见 未来改进).
• 样式：生成的HTML缺少CSS样式，这可能会影响渲染。， `, `)但对原始文档的视觉保真度有限。
• 文件大小：由于Tika的解析和HTML转换开销，大文件可能会影响性能。
• 支持格式：取决于Apache Tika的能力。支持常见格式（PDF、DOCX、TXT、Markdown），但特殊格式可能需要额外的Tika解析器。

未来改进

• 图像支持：将嵌入的图像提取到目录中，并通过专用端点（例如。， /api/images/).
• CSS样式：在HTML输出中包含默认样式表以改进呈现。
• 链接验证：确保HTML输出中的目录和图形链接正确解析。
• 分页：支持对大型文档进行流式或分页响应，以提高性能。
• 元数据丰富：在响应中包含其他Tika元数据（例如字数、创建日期）。
• 文件上传：添加端点以将文件上传到 file-to-extract 动态目录。

故障排除

• 文件未找到错误:

- 确保文件存在于 file-to-extract 目录。 - 检查请求中的文件名是否完全匹配（区分大小写）。

• 端口冲突:

- 中频端口 45452 正在使用中，请在中更新端口 PdfExtractorApplication.java （行： connector.setPort(45452)).

• Tika解析错误:

- 验证Tika是否支持该文件格式。 - 如果问题仍然存在，请将Tika依赖项更新到最新版本。

• 配置问题:

- 确保 application.properties 在...里 src/main/resources/. - 检查一下 file.directory 指向有效目录。

贡献

欢迎投稿！贡献：

1. 分叉存储库。
2. 创建要素分支(git checkout -b feature/YourFeature).
3. 提交更改(git commit -m "Add YourFeature").
4. 推到分支(git push origin feature/YourFeature).
5. 打开一个pull请求。

请根据需要包括测试和更新文档。

联系

如有疑问或需要支持，请联系项目维护人员：

• 名字穆罕默德·拉扬·马卢什
• 电子邮件: rayenmalouche27@gmail.com