AI导哈

文件内容提取服务器

Tika MCP Extractor Server 是一个基于Apache Tika的文件内容提取服务器，支持多种文件格式（如PDF、DOCX、TXT等）的内容和元数据提取，并提供HTML或纯文本转换功能。适用于本地安全文档处理工作流。

  • by RayenMalouche
  • Java
  • 本地部署
  • 更新于
在 GitHub 查看 rayenmalouche/mcp-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

  2. 创建文件目录:

  • 服务器读取 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": "<html><head><style>body { font-family: Arial, sans-serif; ... }</style></head><body>...</body></html>",
  "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<String, Object> result = service.extractToHtml("sample.pdf");
        assertNotNull(result.get("html"));
        assertEquals("application/pdf", result.get("contentType"));
        assertTrue(((String) result.get("html")).contains("<style>"));
    }
}
  • 运行：
    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日

相关 MCP