jooq-mcp

jOOQ MCP 服务

一个可让 AI 模型访问 jOOQ 文档的模型上下文协议（MCP）服务。此 Spring Boot 应用使用 Spring AI 将 jOOQ 文档公开为 MCP 工具，使 AI 系统能够查询和检索有关 jOOQ 功能、SQL 示例和最佳实践的信息。

功能

此 MCP 服务提供以下工具：

• searchDocumentation：搜索 jOOQ 文档中的特定主题
• getSqlExamples：获取特定操作的 SQL 查询构建示例
• getCodeGenerationGuide：检索 jOOQ 代码生成文档
• getDatabaseSupport：获取特定数据库的支持信息
• getQueryDslReference：获取特定语句类型的 Query DSL 参考
• getAdvancedFeatures：访问 jOOQ 高级功能文档

入门

前提条件

• Java 21 或更高版本
• Maven 3.6+

运行应用

1. 克隆代码库：

   git clone <repository-url>
   cd jooq-mcp
   

2. 构建项目：

   ./mvnw clean install
   

3. 运行应用：

   ./mvnw spring-boot:run
   

MCP 服务启动后，即可接受 MCP 客户端的连接。

Docker 部署

1. 构建 JAR 文件：

   ./mvnw clean package
   

2. 构建 Docker 镜像：

   docker build -t jooq-mcp .
   

3. 运行 Docker 容器：

   docker run -p 8080:8080 jooq-mcp
   

Fly.io 部署

此应用已配置为部署到 Fly.io：

1. 安装 Fly CLI 并进行身份验证：

   brew install flyctl  # or your preferred installation method
   fly auth login
   

2. 部署应用：

   ./mvnw clean package
   fly deploy
   

应用包含位于 /actuator/health 的健康检查，并已配置自动扩缩。

与 MCP 客户端配合使用

此服务可与任何兼容 MCP 的 AI 客户端配合使用。服务提供的工具可让 AI 模型执行以下操作：

• 按关键词搜索 jOOQ 文档
• 检索特定的 SQL 示例和代码片段
• 访问特定数据库的配置信息
• 获取代码生成设置指南
• 查找有关 jOOQ 高级功能的信息

配置

可通过 application.properties 配置应用：

# MCP Server Configuration
spring.ai.mcp.server.name=jooq-documentation-mcp
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.capabilities.tool=true

# Cache Configuration
spring.cache.type=caffeine
spring.cache.caffeine.spec=maximumSize=100,expireAfterWrite=1h

# jOOQ Documentation Crawler Configuration
jooq.documentation.crawler.max-depth=4
jooq.documentation.crawler.max-urls-per-section=100
jooq.documentation.crawler.timeout-ms=10000
jooq.documentation.crawler.cache-duration-hours=24

# Server Configuration - SSE Buffer Settings
server.tomcat.max-http-response-header-size=64KB
server.tomcat.max-swallow-size=10MB

使用示例

连接到 MCP 客户端后，你可以提出以下问题：

• “如何在 jOOQ 中创建 SELECT 语句？”
• “给我看看 jOOQ INSERT 操作的示例。”
• “jOOQ 支持哪些数据库？”
• “如何配置 jOOQ 代码生成？”
• “如何在 jOOQ 中使用事务？”

服务会获取相关文档，并提供包含代码示例的详细解答。

架构

此应用由以下部分组成：

• JooqDocumentationService：主要服务类，包含用于 MCP 集成的 @Tool 注解方法
• LocalJooqDocumentationService：提供本地文档索引和基于 TF-IDF 评分的全文搜索
• InvertedIndex：实现具有相关性评分的高级全文搜索功能
• JooqDocumentationCrawler：抓取 jOOQ 文档并获取内容，以便在本地存储
• JooqDocumentationFetcher：负责解析和提取文档内容
• McpConfiguration：用于注册 MCP 工具的 Spring 配置
• Caching：基于 Caffeine 的缓存，可提升性能

主要功能

• 本地文档存储：文档存储在本地 src/main/resources/docs/，以便更快地访问
• 全文搜索：使用 TF-IDF 评分进行高级搜索，以提高相关性
• 高效索引：使用内存倒排索引快速检索文档
• 代码示例提取：自动提取并分类代码示例

测试

运行测试套件：

./mvnw test

开发

此应用使用：

• Spring Boot 3.5.4
• 支持 MCP 服务的 Spring AI 1.0.0
• 用于 HTML 解析的 JSoup
• 用于缓存的 Caffeine

要添加新工具，请在 JooqDocumentationService 类中创建带有 @Tool 注解的方法。