Pdf Extractor Server

Tika MCP提取服务器

概述

这 Tika MCP提取服务器 是一个符合模型上下文协议（MCP）的服务器，它使用 只有 Apache 从存储在数据库中的各种格式（例如PDF、DOCX、TXT、HTML、图像）的文件中提取内容和元数据 files-to-extract 目录。它支持转换为HTML（可选CSS样式以提高可读性）或纯文本，并提供列出文件和检索元数据的工具。内置于 Java 23, Spring Boot, 喷气，以及 MCP-SDK（0.11.0），它与兼容MCP的客户端（如Claude Desktop或MCP Inspector）集成。

服务器暴露 四种MCP工具:

• extract-to-html：将文件内容转换为HTML（内嵌CSS）。
• extract-text：提取纯文本。
• list-available-files：列出目录中的文件及其详细信息。
• get-file-metadata：检索详细的文件元数据。

它还提供 REST端点 用于测试，包括一个新的端点，直接为浏览器渲染提供原始HTML。所有操作都是本地的，不需要互联网接入，使其成为安全文档处理工作流的理想选择。

特性

• 文件提取：使用Apache Tika将文件内容转换为HTML（为了可读性，使用CSS）或纯文本。
• 元数据抽取：检索元数据，如标题、作者、内容类型和创建日期。
• 文件列表：扫描 files-to-extract 对于文件，提供大小、MIME类型和修改详细信息。
• MCP集成：四个具有JSON模式验证的同步工具。
• REST测试端点:

- 获取 /api/test/list：列出可用文件。 - 发布 /api/test/extract-html：将文件内容提取为带有HTML字符串的JSON格式。 - 发布 /api/test/extract-text：将文件内容提取为JSON格式的纯文本。 - 发布 /api/test/raw-html：直接提供原始HTML（可在浏览器中渲染）。 - 获取/发布 /api/health：检查服务器和目录状态。

• CORS支持：已为基于web的测试的所有REST端点启用。
• 可配置性：设置（端口、目录、Tika选项）通过 application.properties.
• 错误处理：对文件存在性、可读性和解析错误进行强有力的检查。
• 日志记录：支持Tika和PDFBox调试的控制台日志。

先决条件

• Java：JDK 23+（使用OpenJDK 24.0.2进行测试）。
• 梅文：用于依赖关系管理和构建的3.6+版本。
• 支持的文件格式：PDF、DOCX、TXT、HTML、图像等，由Apache Tika 2.9.1和PDFBox 2.0.29处理。
• 可选的：IntelliJ IDEA用于开发（输出表示IntelliJ的使用情况，但任何IDE或CLI都可以工作）。
• 本地文件：将文件放置在 files-to-extract 目录；不需要互联网。

安装

1. 克隆存储库 （如果托管）：

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

1. 创建文件目录:

• 服务器读取 files-to-extract （可配置）。
• 创建它：

  mkdir files-to-extract

• 添加示例文件（例如。， sample.pdf, document.docx)用于测试。

1. 构建项目:

• 使用Maven编译和解析依赖关系：

  mvn clean install

• 在中输出可执行JAR文件 target/.

配置

设置在中定义 src/main/resources/application.properties:

# Tika MCP Extractor Server Configuration
spring.application.name=TikaExtractorMCPServer

# Server Configuration
server.port=45453

# Tika Configuration
tika.max.string.length=-1
tika.detect.language=false

# File Processing Configuration
files.directory=files-to-extract
files.max.size=52428800

# Logging Configuration
logging.level.org.apache.tika=DEBUG
logging.level.org.apache.pdfbox=DEBUG

• spring.application.name：Spring Boot的应用程序名称。
• 服务器端口：HTTP端口（默认值：45453）。
• tika.max.string.length：设置Tika的最大字符串长度（-1=无限制）。
• tika.detect.language：禁用语言检测以提高性能。
• files.directory：输入文件的目录。
• files.max.size：最大文件大小（50MB）。
• 日志级别：调试Tika和PDFBox以排除提取问题。

这 ConfigLoader 类在启动时加载这些属性，如果文件丢失或格式错误，则返回默认值。

它是如何运作的

建筑

• 主要班级(PdfExtractorApplication.java):

- 初始化服务器，通过加载配置 ConfigLoader. - 确保 files-to-extract 存在。 - 支持HTTP/SSE（默认或 --streamable-http)或STDIO(--stdio)模式。 - 使用MCP传输、测试和健康servlet配置Jetty服务器。

• 服务层(TikaExtractorService.java):

- 使用Apache Tika的核心提取逻辑。 - 方法： - extractToHtml：生成内嵌CSS的HTML（通过 ToHTMLContentHandler). - extractText：使用提取纯文本 BodyContentHandler. - listAvailableFiles：扫描目录，返回文件详细信息（大小、MIME等）。 - getFileMetadata：提取元数据（例如。， TikaCoreProperties.TITLE, CREATOR). - 验证文件的存在性和可读性。

• MCP工具(McpToolsProvider.java):

- 定义了四个具有JSON模式和处理程序的工具。 - 呼叫 TikaExtractorService 并格式化JSON响应（HTML包括CSS）。 - 使用标准化的JSON消息处理错误。

• Web层:

- TestServlet.java：用于测试的REST端点，包括 /raw-html 用于直接HTML渲染。 - HealthServlet.java：检查服务器状态和目录可访问性。 - 支持web客户端的CORS。

• 依赖项:

- Tika（2.9.1）：解析文件；PDFBox（2.0.29）支持PDF格式。 - MCP SDK（0.11.0）：符合MCP协议。 - Jetty（12.0.18）：HTTP服务器。 - Jackson（2.15.2）：JSON处理。 - Spring Boot：管理依赖关系和配置。

工作流程

1. 放置文件（例如。， sample.pdf)in files-to-extract.
2. 启动服务器。
3. 使用MCP客户端调用工具（例如。， extract-to-html 随着 {"filename": "sample.pdf"}).
4. 或者，使用REST端点：

• JSON响应：POST /api/test/extract-html.
• 原始HTML:POST /api/test/raw-html （可在浏览器中渲染）。

1. 服务器解析文件，返回JSON或HTML，并嵌入CSS以获得更好的格式。

运行服务器

HTTP/SSE模式

• web或MCP检查器的默认模式：

  mvn spring-boot:run

• 流式HTTP（用于MCP检查器）：

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

• 输出：

  Configuration loaded. Server port: 45453
  Directory exists: files-to-extract
  Starting Tika MCP server with HTTP/SSE transport...
  Tika MCP Extractor Server started on port 45453
  Mode: Standard HTTP/SSE
  MCP endpoint: http://localhost:45453/
  SSE endpoint: http://localhost:45453/sse
  Test endpoints:
    - List files: GET http://localhost:45453/api/test/list
    - Extract HTML: POST http://localhost:45453/api/test/extract-html
    - Extract text: POST http://localhost:45453/api/test/extract-text
    - Raw HTML: POST http://localhost:45453/api/test/raw-html
  Health check: http://localhost:45453/api/health
  Files directory: ./files-to-extract/

STDIO模式

• 对于命令行或本地MCP客户端：

  mvn spring-boot:run -- --stdio

IDE（IntelliJ）

• 跑 PdfExtractorApplication 主要方法。
• 本地访问警告：IntelliJ的运行时会触发警告。忽略或添加到VM选项：

  --enable-native-access=ALL-UNNAMED

按Ctrl+C停止。

用法

MCP工具

• 客户端：使用符合MCP的工具（例如MCP检查器、Claude Desktop）。
• 有效载荷：带工具参数的JSON：

  {
    "filename": "sample.pdf"
  }

• 工具:

- extract-to-html：退货 {"status": "success", "filename": "...", "contentType": "...", "htmlLength": ..., "html": "..."} （HTML包括CSS）。 - extract-text：返回JSON格式的纯文本。 - list-available-files：返回包含大小、MIME等的文件列表。 - get-file-metadata：返回元数据映射。

• 错误: {"status": "error", "message": "..."}.

REST端点

使用CURL、Postman或浏览器进行测试：

• 列出文件:

  curl http://localhost:45453/api/test/list

答复：

  {
    "files": {
      "sample.pdf": {
        "size": 123456,
        "lastModified": 1698765432000,
        "canRead": true,
        "mimeType": "application/pdf"
      }
    },
    "count": 1,
    "path": ".../files-to-extract"
  }

• 提取HTML（JSON）:

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

答复：

  {
    "filename": "sample.pdf",
    "html": "body { font-family: Arial, sans-serif; ... }...",
    "contentType": "application/pdf",
    "title": "Sample Document",
    "author": "John Doe"
  }

• 提取原始HTML:

  curl -X POST http://localhost:45453/api/test/raw-html \
       -H "Content-Type: application/json" \
       -d '{"filename":"sample.pdf"}' > output.html

- 打开 output.html 在浏览器中查看样式化的HTML。

• 提取文本:

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

• 健康检查:

  curl http://localhost:45453/api/health

答复：

  {
    "status": "ok",
    "server": "Tika MCP Extractor Server",
    "version": "1.0.0",
    "filesDirectoryExists": true,
    "filesDirectoryReadable": true,
    "filesDirectoryWritable": true
  }

测试

单元测试

• 在中添加JUnit测试 src/test/java:

  import org.junit.jupiter.api.Test;
  import static org.junit.jupiter.api.Assertions.*;
  import com.mcp.RayenMalouche.pdf.PDFExtractor.Service.TikaExtractorService;

  class TikaExtractorServiceTest {
      @Test
      void testPdfExtraction() throws Exception {
          TikaExtractorService service = new TikaExtractorService();
          Map result = service.extractToHtml("sample.pdf");
          assertNotNull(result.get("html"));
          assertEquals("application/pdf", result.get("contentType"));
          assertTrue(((String) result.get("html")).contains(""));
      }
  }

• 运行：

  mvn test

• 注：确保 sample.pdf 存在于 files-to-extract 用于测试。

手动测试

1. 将文件放入 files-to-extract （例如。， sample.pdf).
2. 启动服务器。
3. 使用CURL/Postman测试REST端点：

• 验证 /raw-html 在浏览器中渲染（将输出保存到 .html 文件）。
• 检查 /extract-html 用于带有样式化HTML的JSON。

1. 对于MCP，使用MCP检查器或通过HTTP POST进行模拟 / 或 /message.
2. 检查日志中的错误（例如，“提取到html时出错”）。

边缘案例

• 文件不存在：退货 {"status": "error", "message": "File not found: ..."} 或HTML错误页面 /raw-html.
• 大文件：受限于 files.max.size （50MB）；调整属性。
• 不支持的格式：如果可能的话，Tika会退回到文本提取。

项目结构

PDFExtractor/
├── src/
│   ├── main/
│   │   ├── java/com/mcp/RayenMalouche/pdf/PDFExtractor/
│   │   │   ├── PdfExtractorApplication.java  # Main entry point
│   │   │   ├── config/
│   │   │   │   └── ConfigLoader.java        # Loads properties
│   │   │   ├── Service/
│   │   │   │   └── TikaExtractorService.java  # Extraction logic
│   │   │   ├── tools/
│   │   │   │   └── McpToolsProvider.java    # MCP tools
│   │   │   ├── web/
│   │   │   │   ├── TestServlet.java         # REST test endpoints
│   │   │   │   └── HealthServlet.java       # Health check
│   │   ├── resources/
│   │   │   └── application.properties       # Configuration
│   ├── test/                                # Add tests here
├── files-to-extract/                        # Input files
├── pom.xml                                  # Maven config
├── target/                                  # Build artifacts
├── README.md                                # This file

依赖项

自 pom.xml:

• 弹簧靴（3.5.5）：框架基础。
• MCP-SDK（0.11.0）：MCP协议支持（注意：已弃用API）。
• 码头（12.0.18）：嵌入式HTTP服务器。
• 杰克逊（2.15.2）：JSON处理。
• 只有 （2.9.1）：文件解析。
• PDFBox（2.0.29）：PDF支持（降级为修复 NoSuchMethodError).
• Commons IO（2.11.0），Commons编解码器（1.15）：文件实用程序。
• 跑 mvn dependency:tree 查看完整列表。

局限性

• 弃用的API：MCP SDK 0.11.0使用已弃用的 Tool 建设者。稳定后更新到最新的SDK。
• 图像处理：文件（例如DOCX）中的嵌入式图像被引用（例如。， src="embedded:image1.jpg")但未提取/食用。
• 无文件上传：文件必须手动放置在 files-to-extract.
• 演出：大文件可能会占用内存；没有异步处理。
• 安全：端点没有身份验证；仅限本地使用。
• 本地访问警告：IntelliJ运行时触发警告--可以安全地忽略或添加 --enable-native-access=ALL-UNNAMED.

未来改进

• 图像提取：通过新的端点提取并提供嵌入式图像。
• 文件上传端点：允许动态文件上传到 files-to-extract.
• 更新MCP SDK：迁移到最新版本以解决弃用问题。
• 异步处理：对大文件使用反应式流。
• 完整的Spring Boot集成：用Spring的嵌入式Tomcat/WebFlux替换Jetty。
• 认证：为REST端点添加基本身份验证。
• 单元测试：扩大所有组件的测试覆盖范围。
• CI/CD：添加GitHub Actions以进行自动化构建/测试。

故障排除

• 本地访问警告:

- IntelliJ相关： WARNING: java.lang.System::load has been called.... - 修复：添加 --enable-native-access=ALL-UNNAMED 选择VM选项或忽略。

• 端口冲突:

- 改变 server.port 在……里面 application.properties.

• 找不到文件:

- 确保文件存在于 files-to-extract 并与案件相匹配。

• PDF提取错误:

- 通过降级到PDFBox 2.0.29（解决 NoSuchMethodError). - 启用 logging.level.org.apache.pdfbox=DEBUG 用于诊断。

• 只有错误:

- 验证文件格式支持；如果需要，更新蒂卡。

• 构建问题:

- 跑 mvn clean install；确保JDK 23+。 - 检查Maven依赖项是否存在冲突(mvn dependency:tree | grep pdfbox).

贡献

1. 分叉存储库。
2. 创建要素分支： git checkout -b feature/YourFeature.
3. 提交更改： git commit -m "Add YourFeature".
4. 推： git push origin feature/YourFeature.
5. 打开一个包含测试用例和文档的pull请求。

联系

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

最后更新：2025年8月30日