jOOQ MCP 服务器

这是一个模型上下文协议（MCP）服务器，提供AI模型访问jOOQ文档的功能。此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  # 或您首选的安装方法
   fly auth login
   

2. 部署应用程序：

   ./mvnw clean package
   fly deploy
   

应用程序包括在/actuator/health的健康检查，并配置了自动扩展。

使用MCP客户端

此服务器可以与任何兼容MCP的AI客户端一起使用。服务器公开的工具允许AI模型：

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

配置

应用程序可以通过application.properties进行配置：

# MCP服务器配置
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

# 缓存配置
spring.cache.type=caffeine
spring.cache.caffeine.spec=maximumSize=100,expireAfterWrite=1h

# jOOQ文档爬虫配置
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

# 服务器配置 - SSE缓冲设置
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：Spring配置，用于MCP工具注册
• 缓存：基于Caffeine的缓存以提高性能

关键特性

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

测试

运行测试套件：

./mvnw test

开发

应用程序使用：

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

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