使用说明

项目简介

'mcp-server-sql' 是一个基于 Spring Boot 和 Spring AI MCP 框架构建的 SQL 服务应用。它旨在作为 MCP (Model Context Protocol) 服务器，为大型语言模型 (LLM) 提供 SQL 数据库的访问能力，允许 LLM 通过调用该服务执行 SQL 查询和更新操作，并将结果返回或保存到文件中。该服务可以作为 LLM 的工具，扩展其数据访问和处理能力。

主要功能点

SQL 查询执行: 允许 LLM 提交 SQL 查询语句，服务执行查询并将结果以 CSV 格式写入指定文件。
SQL 更新操作执行: 支持 LLM 执行 SQL INSERT、UPDATE、DELETE 等更新语句，服务执行更新并返回受影响的行数。
动态数据源配置: 支持在请求中动态指定数据库连接信息（URL、用户名、密码等），或使用默认配置，提高了灵活性。
结果持久化: 查询和更新操作的结果可以保存到指定的文件路径，方便后续分析和使用。
Spring AI MCP 集成: 无缝集成 Spring AI MCP 框架，可以方便地作为 AI 工具被 LLM 客户端调用。

安装步骤

前提条件: 确保已安装 Java 17 和 Maven。
下载代码: 从 GitHub 仓库 'https://github.com/cherry-SC/mcp-server-sql' 克隆代码到本地。

配置数据库: 修改 'application.yml' 文件，配置您的 MySQL 数据库连接信息。

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/your_database?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: your_username
    password: your_password

构建项目: 在项目根目录下运行 Maven 命令进行构建：
```
mvn clean package
```
构建成功后，会在 'target' 目录下生成 'mcp-server-Sql-1.0-SNAPSHOT.jar' 文件。
运行应用: 运行生成的 JAR 文件启动 MCP 服务器：
```
java -jar target/mcp-server-Sql-1.0-SNAPSHOT.jar
```
看到控制台输出 'mcp-server-sql start success' 表示服务器启动成功。

服务器配置 (MCP 客户端配置)

以下 JSON 配置信息用于 MCP 客户端连接和使用 'mcp-server-sql' 服务。客户端需要配置 'command' 和 'args' 来启动服务器进程。

{
  "serverName": "sql-server",  // 自定义服务器名称，用于在客户端标识
  "command": "java",         // 启动服务器的命令，这里使用 java
  "args": [                  // 启动命令的参数
    "-jar",                 // 指定运行 jar 文件
    "target/mcp-server-Sql-1.0-SNAPSHOT.jar" //  jar 文件路径，相对于客户端工作目录，如果客户端与服务端部署在不同机器，需要修改为服务端可执行的jar路径
  ],
  "protocol": "stdio",      // 假设客户端通过标准输入输出流 (stdio) 与服务器通信，根据实际情况调整
  "description": "SQL数据库操作服务，提供查询和更新功能" //  对该服务器的描述，方便客户端用户理解
}

参数注释:

'serverName': 为该 SQL 服务自定义一个名称，在 MCP 客户端中用于唯一标识和引用该服务。
'command': 启动 'mcp-server-sql' 服务进程的命令，通常为 'java'，表示使用 Java 运行时环境。
'args': 传递给启动命令的参数列表。
- '"-jar"': Java 命令参数，指示运行一个 JAR 文件。
- '"target/mcp-server-Sql-1.0-SNAPSHOT.jar"': 'mcp-server-sql' 服务 JAR 文件的路径。请注意，此路径是相对于 MCP 客户端的执行目录。 如果客户端和服务端部署在不同机器，需要确保客户端能够访问到服务端的可执行 JAR 文件，或者将 JAR 文件路径修改为服务端实际部署路径。
'protocol': 指定 MCP 客户端与服务器通信的协议。这里假设使用 'stdio' (标准输入输出流)，实际应用中可能需要根据 'mcp-server-sql' 的具体实现和客户端支持的协议进行调整，例如 'websocket' 或 'sse'。如果 'mcp-server-sql' 实现了基于 JSON-RPC over Stdio 的协议，则 'stdio' 配置是合适的。
'description': 对该 SQL 服务的简要描述，用于在 MCP 客户端界面或配置中展示，帮助用户理解该服务的功能。

注意: 上述配置是一个基础示例，实际 MCP 客户端可能需要更多的配置项，例如服务器的能力声明、支持的工具列表等。您需要参考具体的 MCP 客户端文档以及 'mcp-server-sql' 的完整实现来获取更详细的配置信息。目前根据仓库信息，我们可以推断 'mcp-server-sql' 通过 Spring AI 的 '@Tool' 注解暴露功能，并可能通过 Spring AI MCP 框架处理与客户端的通信，但具体的 MCP 协议细节和传输方式需要进一步的代码分析或文档确认。这里假设其使用 Stdio 协议进行通信，并需要通过 Java 命令启动 JAR 包。

基本使用方法

启动 MCP 客户端: 确保您已经安装并配置了支持 MCP 协议的 LLM 客户端。
配置 MCP 服务器: 在 MCP 客户端中，添加上述提供的 JSON 配置，将 'mcp-server-sql' 服务注册到客户端。

调用 SQL 工具: 在 LLM 客户端中，您可以指示 LLM 使用 "sql-server" (或您配置的 'serverName') 服务提供的工具来执行 SQL 操作。

执行 SQL 查询: 发送类似以下的 JSON 请求给 "sql-server" 服务的 'executeQuery' 工具：

{
  "sql": "SELECT * FROM users WHERE age > 18",
  "outputPath": "./output/adult_users.csv"
}

执行 SQL 更新操作: 发送类似以下的 JSON 请求给 "sql-server" 服务的 'executeUpdate' 工具：

{
  "sql": "UPDATE users SET status='active' WHERE last_login < DATE_SUB(NOW(), INTERVAL 3 MONTH)",
  "outputPath": "./output/inactive_users_updated.txt"
}

查看结果: 服务执行 SQL 操作后，结果将写入指定的 'outputPath' 文件中。您可以查看文件内容获取查询结果或更新操作的详细信息。

请注意: 上述使用示例是假设 MCP 客户端能够发送 JSON 请求并调用 "sql-server" 服务提供的 'executeQuery' 和 'executeUpdate' 工具。具体的工具调用方式和请求格式需要参考 MCP 客户端的文档以及 'mcp-server-sql' 服务实际暴露的工具接口定义。这里提供的示例请求结构是基于 'src/main/java/com/sc/mcp/server/sql/domain/model/SqlFunctionRequest.java' 文件中定义的请求参数推断的。

关键词