AI导哈

PDF处理工具服务器

一个基于Spring Boot的MCP服务器，提供PDF文件处理功能，包括获取页数、提取文本、获取元数据、压缩和拆分PDF，适用于AI模型集成。

  • by an1shthomas
  • Java
  • 本地部署
  • 更新于
在 GitHub 查看 an1shthomas/pdf-mcp-server

使用说明

PDF工具MCP服务器

概述

此存储库包含一个Spring Boot应用程序，该应用程序实现了用于PDF处理操作的模型上下文协议（MCP）服务器。该应用程序创建了一个轻量级服务器，通过Spring AI MCP框架公开PDF操作工具，允许AI模型使用Docker容器API与PDF文件交互。

服务器公开了五个主要的PDF处理工具：

  • 从PDF文件中获取页数
  • 从PDF中提取文本内容
  • 检索PDF元数据
  • 压缩PDF文件
  • 将PDF拆分为单独的页面

此实现为通过模型上下文协议将PDF处理功能与AI模型集成奠定了良好的基础。

项目需求

  • Java 21+
  • Maven 3.8+
  • 弹簧靴3.4.4
  • 春季AI 1.0.0-M6
  • Docker容器在端口8081上运行PDF处理API

依赖项

该项目依赖于以下关键依赖关系：

  • Spring AI MCP服务器：为创建MCP兼容服务器提供基础

    <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>

  • Spring Boot WebFlux：用于响应式HTTP客户端操作

    <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

  • 弹簧靴测试：用于测试应用程序

    <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

入门指南

先决条件

在运行应用程序之前，请确保您已经：

  • 您的系统上已安装Java 21+
  • 安装Maven进行依赖管理
  • 带有PDF处理API的Docker容器在端口8081上运行
  • 对Spring Boot应用程序的基本了解

Docker容器要求

您的PDF处理Docker容器必须公开以下API端点：

  • POST /api/v1/analysis/page-count -获取页面计数
  • POST /api/v1/convert/pdf/txt -提取文本内容
  • POST /api/v1/analysis/metadata -获取PDF元数据
  • POST /api/v1/misc/compress-pdf -压缩PDF文件
  • POST /api/v1/general/split-pages -将PDF拆分为页面

设置项目

  1. 审查项目结构，了解组成部分：

    • PdfAnalysisResult.java：用于标准化PDF操作响应的记录
    • PdfService.java：使用MCP工具注释进行PDF操作的服务
    • CoursesApplication.java：带有工具注册的主应用程序类
    • application.properties：MCP服务器和PDF API的配置

  2. 该应用程序被配置为使用用于MCP通信的STDIO传输作为非web应用程序运行：

    spring.main.web-application-type=none
spring.ai.mcp.server.name=pdf-tools-mcp
spring.ai.mcp.server.version=1.0.0

# PDF API Configuration
pdf.api.base-url=http://localhost:8081

# These settings are critical for STDIO transport
spring.main.banner-mode=off
logging.pattern.console=

如何建造和运行

构建应用程序

mvn clean package

运行应用程序

mvn spring-boot:run

或者直接运行JAR：

java -jar target/pdf-tools-mcp-1.0.0-SNAPSHOT.jar

该应用程序将作为可通过标准输入/输出访问的模型控制协议服务器启动。它不打开任何网络端口或提供web界面，如 spring.main.web-application-type=none 配置。

运行时，服务器向MCP注册了五个PDF处理工具：

  • pdf_get_page_count：获取PDF文件中的页数
  • pdf_extract_text：从PDF文件中提取文本内容
  • pdf_get_metadata：从PDF文件获取元数据信息
  • pdf_compress：压缩PDF文件以减小其大小
  • pdf_split_pages：将PDF文件拆分为单独的页面

理解代码

PDF数据模型

应用程序使用记录来表示PDF操作结果：

public record PdfAnalysisResult(
    String operation,
    String filename,
    Object result,
    boolean success,
    String message
) {
    // Factory methods for success and error responses
}

实施PDF工具

这 PdfService 类演示了如何使用 @Tool 注释：

@Service
public class PdfService {
    @Tool(name = "pdf_get_page_count", description = "Get the number of pages in a PDF file")
    public PdfAnalysisResult getPageCount(String filePath) {
        // Implementation that calls Docker container API
    }
    
    @Tool(name = "pdf_extract_text", description = "Extract text content from a PDF file")
    public PdfAnalysisResult extractText(String filePath) {
        // Implementation that calls Docker container API
    }
    
    // Additional PDF tools...
}

这 @Tool 注释将常规方法转换为MCP兼容工具，包括：

  • 用于识别的唯一名称
  • 帮助AI模型理解工具目的的描述

向MCP注册工具

在主应用程序类中，工具在MCP框架中注册：

@SpringBootApplication
public class CoursesApplication {
    @Bean
    public List<ToolCallback> pdfTools(PdfService pdfService) {
        return List.of(ToolCallbacks.from(pdfService));
    }
}

配置

PDF API配置

在中配置Docker容器API端点 application.properties:

pdf.api.base-url=http://localhost:8081

要使用其他主机或端口，请相应地更新此属性。

使用带有AI模型的MCP服务器

要将此MCP服务器与AI模型一起使用：

  1. 确保您的AI框架支持模型控制协议
  2. 确保你的Docker容器在8081端口上运行并可访问
  3. 使用STDIO传输将AI模型连接到MCP服务器
  4. 然后，AI模型可以调用公开的PDF工具

LM Studio的配置

要将此MCP服务器与LM Studio一起使用，请将以下配置添加到您的 mcp_servers.json:

{
  "servers": {
    "pdf-tools-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "/Users/anishthomas/Downloads/dv-courses-mcp-master/target/pdf-tools-mcp-1.0.0-SNAPSHOT.jar"
      ],
      "description": "PDF Processing Tools MCP Server"
    }
  }
}

重要提示：

  • 确保使用正确的JAR文件名： pdf-tools-mcp-1.0.0-SNAPSHOT.jar
  • 调整完整路径以匹配您的特定环境
  • 如果您之前有一个配置指向 courses-0.0.1-SNAPSHOT.jar，将其更新为新的JAR名称
  • 更新配置后，重新启动LM Studio或重新加载MCP服务器

常见配置错误： 如果您看到类似“无法访问jarfile”的错误，请确保您使用的是正确的JAR文件路径。该项目已重命名为 courses 向 pdf-tools-mcp，因此JAR文件名相应地更改。

Claude桌面配置

要将此MCP服务器与Claude Desktop一起使用，请将以下内容添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-tools-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/pdf-tools-mcp-1.0.0-SNAPSHOT.jar"
      ]
    }
  }
}

示例使用

一旦与MCP客户端集成，您可以使用以下提示：

  • “PDF文件/用户/用户名/文档/报告.PDF中有多少页？”
  • “从/path/to/contract.pdf中提取文本并总结要点”
  • “从/Users/username/Documents/presentation.pdf获取元数据”
  • “压缩/path/to/large-file.pdf并将其另存为/path/to/compressed.pdf”
  • “将/Users/username/Documents/multi-page.pdf拆分为/Users/Users/Documents/output/中的各个页面”

错误处理

PDF工具包括以下全面的错误处理：

  • 找不到文件错误
  • Docker容器API的HTTP错误
  • 网络超时
  • 文件路径无效
  • API不可用

性能注意事项

  • 文件大小限制：WebClient配置为处理最大50MB的文件
  • 超时：30-120秒，具体取决于操作复杂性
  • 内存使用情况：大型PDF操作可能需要额外的JVM内存

故障排除

常见问题

  1. Docker容器不可访问：确保您的容器在端口8081上运行
  2. 找不到文件错误：使用绝对文件路径
  3. 超时错误：大型PDF可能需要更长的处理时间
  4. 连接被拒绝：验证Docker容器端口映射

Docker容器测试

直接测试Docker容器：

curl -X POST http://localhost:8081/api/v1/analysis/page-count \
  -F "fileInput=@/path/to/test.pdf"

扩展项目

您可以通过以下方式扩展此项目：

  1. 添加更多PDF操作：实施额外 @Tool 带注释的方法
  2. 支持更多文件格式：扩展以处理其他文档类型
  3. 添加批处理：实现处理多个文件的工具
  4. 增强的错误处理：添加更复杂的错误恢复

结论

此PDF工具MCP服务器提供了一个干净、可扩展的框架，用于通过模型上下文协议公开PDF处理功能。通过利用Spring AI惯例和工具注释系统，您可以在AI模型和PDF处理服务之间创建强大的集成。

该项目演示了如何构建代码以实现MCP兼容性，同时保持良好的软件设计实践并与基于Docker的外部服务集成。

有关Spring AI和模型上下文协议的更多信息，请参阅官方文档。

相关 MCP