# jdbc_mcp_server

**Repository Path**: awol2010ex/jdbc_mcp_server

## Basic Information

- **Project Name**: jdbc_mcp_server
- **Description**: 一个基于Solon框架的JDBC数据库连接管理和SQL执行服务，支持MCP (Model Context Protocol) 协议和OpenAPI文档。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-21
- **Last Updated**: 2026-02-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JDBC MCP Server

一个基于Solon框架的JDBC数据库连接管理和SQL执行服务，支持MCP (Model Context Protocol) 协议和OpenAPI文档。

## 功能特性

- 🔐 **用户认证与授权**: JWT token认证，支持管理员和普通用户角色
- 🗄️ **数据库连接管理**: 支持多种数据库连接管理
- 🔒 **权限控制**: 细粒度的数据库连接权限控制
- 🚀 **MCP协议支持**: 提供MCP工具接口，支持AI助手集成（包括Trae、Cursor等）
- 📚 **OpenAPI文档**: 完整的Swagger文档，支持Knife4j界面
- 🔧 **多数据库支持**: MySQL, PostgreSQL, Oracle, DB2, Vertica, Hive, ClickHouse
- ⚡ **高性能**: 基于Solon框架，性能优异

## 快速开始

### 环境要求

- Java 17+
- Maven 3.6+

### 构建项目

```bash
mvn clean package -DskipTests
```

### 运行应用

```bash
java -jar target/jdbc-mcp-server-1.0.0.jar
```

### 默认管理员账户

应用启动时会自动创建管理员账户：
- 用户名: `admin`
- 密码: `admin123`
- 管理员Token会在控制台输出

## MCP客户端集成

### Trae IDE集成

在Trae中配置MCP服务器：

1. 打开Trae设置
2. 找到MCP配置选项
3. 添加新的MCP服务器：

```json
{
  "mcpServers": {
    "jdbc-mcp-server": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your_token_here>"
      }
    }
  }
}
```

### Cursor IDE集成

在Cursor中配置MCP服务器：

1. 打开Cursor设置
2. 找到MCP配置
3. 添加新的MCP服务器配置

### 其他支持MCP的LLM客户端

任何支持MCP协议的LLM客户端都可以使用以下配置：

```json
{
  "mcpServers": {
    "jdbc-mcp-server": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your_token_here>"
      }
    }
  }
}
```

## MCP工具使用

### 可用的MCP工具

1. **ping** - 测试服务器连接
2. **getAvailableConnections** - 获取用户有权限的数据库连接列表
3. **getDatabases** - 获取指定连接的数据库列表
4. **getTables** - 获取指定数据库的表列表
5. **getColumns** - 获取指定表的字段信息
6. **executeSql** - 执行SQL查询

### MCP客户端代码示例

#### 基本MCP客户端使用

```java
// 创建MCP客户端
McpClientProvider client = McpClientProvider.builder()
    .channel(McpChannel.STREAMABLE_STATELESS)
    .url("http://localhost:8080/mcp")
    .timeout(30)
    .build();

// 测试连接
String result = client.callToolAsText("ping", new HashMap<>());
System.out.println("Ping结果: " + result);
```

#### 带认证的MCP客户端

```java
// 创建带认证的MCP客户端
McpClientProvider authClient = McpClientProvider.builder()
    .channel(McpChannel.STREAMABLE_STATELESS)
    .url("http://localhost:8080/mcp")
    .header("Authorization", "Bearer your_token_here")
    .timeout(30)
    .build();

// 获取可用连接
Map<String, Object> params = new HashMap<>();
String connections = authClient.callToolAsText("getAvailableConnections", params);
System.out.println("连接列表: " + connections);

// 执行SQL查询
Map<String, Object> sqlParams = new HashMap<>();
sqlParams.put("connectionId", 1);
sqlParams.put("sql", "SELECT 'Hello MCP' as message");
sqlParams.put("format", "markdown");

String sqlResult = authClient.callToolAsText("executeSql", sqlParams);
System.out.println("SQL结果: " + sqlResult);
```

#### 获取数据库信息

```java
// 获取数据库列表
Map<String, Object> dbParams = new HashMap<>();
dbParams.put("connectionId", 1);
String databases = authClient.callToolAsText("getDatabases", dbParams);

// 获取表列表
Map<String, Object> tableParams = new HashMap<>();
tableParams.put("connectionId", 1);
tableParams.put("databaseName", "main");
String tables = authClient.callToolAsText("getTables", tableParams);

// 获取表字段信息
Map<String, Object> columnParams = new HashMap<>();
columnParams.put("connectionId", 1);
columnParams.put("tableName", "users");
String columns = authClient.callToolAsText("getColumns", columnParams);
```

## 数据库支持

支持以下数据库及其JDBC驱动：

- **MySQL**: `com.mysql:mysql-connector-j:8.0.33`
- **PostgreSQL**: `org.postgresql:postgresql:42.7.1`
- **Oracle**: `com.oracle.database.jdbc:ojdbc11:23.3.0.23.09`
- **DB2**: `com.ibm.db2:jcc:11.5.9.0`
- **Vertica**: `com.vertica.jdbc:vertica-jdbc:25.3.0-0`
- **Hive**: `org.apache.hive:hive-jdbc:3.1.3` (standalone)
- **ClickHouse**: `com.clickhouse:clickhouse-jdbc:0.6.0`

## 数据库配置

### SQLite数据库

项目使用SQLite作为元数据库，数据库文件为 `knowledge.db`，包含以下表：

#### users表
```sql
CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    role VARCHAR(20) DEFAULT 'readonly' NOT NULL,
    token VARCHAR(255),
    tokenExpiresAt TIMESTAMP,
    createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
```

#### databaseConnections表
```sql
CREATE TABLE databaseConnections (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(100) NOT NULL,
    dbType VARCHAR(20) NOT NULL,
    host VARCHAR(255),
    port INTEGER,
    databaseName VARCHAR(100),
    username VARCHAR(100),
    password VARCHAR(255),
    url VARCHAR(500),
    description VARCHAR(500),
    connectionParams VARCHAR(500),
    createdBy INTEGER NOT NULL,
    createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (createdBy) REFERENCES users(id)
)
```

#### userPermissions表
```sql
CREATE TABLE userPermissions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    userId INTEGER NOT NULL,
    connectionId INTEGER NOT NULL,
    permissionType VARCHAR(20) NOT NULL,
    grantedBy INTEGER NOT NULL,
    grantedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (userId) REFERENCES users(id),
    FOREIGN KEY (connectionId) REFERENCES databaseConnections(id),
    FOREIGN KEY (grantedBy) REFERENCES users(id),
    UNIQUE(userId, connectionId)
)
```

## 配置说明

### 应用配置

应用使用Solon框架，配置文件位于 `src/main/resources/app.properties`：

```properties
server.port=8081
server.host=0.0.0.0

# 数据库配置
solon.dataSources.knowledgeDb.class=org.sqlite.SQLiteDataSource
solon.dataSources.knowledgeDb.url=jdbc:sqlite:./knowledge.db
solon.dataSources.knowledgeDb.initSql=RUNSCRIPT FROM 'classpath:schema.sql'

# JWT配置
jwt.secret=your-secret-key-here
jwt.expiration=86400000
```

### MCP客户端配置

MCP客户端配置示例位于 `src/main/resources/mcp-config.yml`：

```yaml
mcp:
  servers:
    jdbc-mcp-server:
      url: "http://localhost:8081/mcp"
      headers:
        Authorization: "Bearer <your_token_here>"
```

### 日志配置

日志配置位于 `src/main/resources/logback.xml`，支持控制台和文件输出。

## 完整MCP客户端使用示例

### 1. 获取管理员Token

首先需要通过登录获取管理员Token：

```bash
curl -X POST http://localhost:8081/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'
```

### 2. 配置Trae IDE

在Trae中配置MCP服务器：

```json
{
  "mcpServers": {
    "jdbc-mcp-server": {
      "url": "http://localhost:8081/mcp",
      "headers": {
        "Authorization": "Bearer <your_admin_token>"
      }
    }
  }
}
```

### 3. 在Trae中使用MCP工具

配置完成后，你可以在Trae中直接使用自然语言与数据库交互：

**示例1：查看可用连接**
```
帮我查看一下有哪些数据库连接可用？
```

**示例2：执行SQL查询**
```
在连接1上执行：SELECT * FROM users LIMIT 5
```

**示例3：获取表结构**
```
帮我看看users表有哪些字段？
```

### 4. 在代码中使用MCP客户端

```java
import com.jdbcmcp.config.McpClientConfig;
import org.noear.mcp.client.McpClientProvider;
import org.noear.mcp.client.McpChannel;

public class DatabaseExplorer {
    public static void main(String[] args) {
        // 创建MCP客户端
        McpClientProvider client = McpClientProvider.builder()
            .channel(McpChannel.STREAMABLE_STATELESS)
            .url("http://localhost:8081/mcp")
            .header("Authorization", "Bearer your_token_here")
            .timeout(30)
            .build();
        
        try {
            // 1. 测试连接
            String pingResult = client.callToolAsText("ping", new HashMap<>());
            System.out.println("✅ 服务器连接正常: " + pingResult);
            
            // 2. 获取可用连接
            String connections = client.callToolAsText("getAvailableConnections", new HashMap<>());
            System.out.println("📊 可用连接: " + connections);
            
            // 3. 执行查询
            Map<String, Object> queryParams = new HashMap<>();
            queryParams.put("connectionId", 1);
            queryParams.put("sql", "SELECT COUNT(*) as user_count FROM users");
            queryParams.put("format", "markdown");
            
            String queryResult = client.callToolAsText("executeSql", queryParams);
            System.out.println("🔍 查询结果: " + queryResult);
            
        } catch (Exception e) {
            System.err.println("❌ MCP调用失败: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
```

### 5. 常见使用场景

**场景1：数据探索**
```
我想了解数据库中有哪些表，以及它们的结构
```

**场景2：数据分析**
```
帮我统计一下users表中不同角色的用户数量
```

**场景3：数据验证**
```
检查一下orders表中是否有数据异常，比如负数的订单金额
```

**场景4：报表生成**
```
生成一份最近30天的用户注册统计报表
```

## 开发指南

### API文档

访问 http://localhost:8081/doc.html 查看完整的OpenAPI文档和测试界面。

主要API分组：
- **JDBC MCP Server API**: 主要的业务API接口
- **MCP Tools API**: MCP协议工具接口

### 项目结构

```
src/main/java/com/jdbcmcp/
├── config/          # 配置类
│   ├── McpClientConfig.java      # MCP客户端配置
│   ├── OpenApiConfig.java      # OpenAPI配置
│   └── GlobalAuthInterceptor.java  # 全局认证拦截器
├── controller/      # 控制器
│   ├── AuthController.java           # 认证接口
│   ├── DatabaseConnectionController.java  # 数据库连接管理
│   └── PermissionController.java       # 权限管理
├── demo/           # 演示和测试
│   ├── McpClientDemo.java      # MCP客户端演示
│   └── McpCliTest.java        # MCP命令行测试工具
├── model/          # 数据模型
│   ├── User.java              # 用户模型
│   ├── DatabaseConnection.java    # 数据库连接模型
│   └── UserPermission.java        # 用户权限模型
├── service/        # 业务服务
│   ├── UserService.java           # 用户服务
│   ├── DatabaseConnectionService.java  # 数据库连接服务
│   └── PermissionService.java       # 权限服务
├── test/          # 测试工具
│   ├── HttpMcpTest.java      # HTTP MCP测试
│   └── McpFunctionTest.java    # MCP功能测试
├── utils/          # 工具类
│   ├── JwtUtils.java           # JWT工具
│   ├── PasswordUtils.java    # 密码工具
│   └── SqlResultFormatter.java   # SQL结果格式化
└── mcp/           # MCP工具
    └── JdbcMcpTools.java        # 数据库探索和SQL执行工具

src/main/resources/
├── app.properties          # 应用配置
├── mcp-config.yml         # MCP客户端配置示例
├── schema.sql            # 数据库初始化脚本
└── logback.xml          # 日志配置
```

### 安全最佳实践

1. **DTO模式**: 使用数据传输对象(DTO)隔离用户输入和实体对象
   - `CreateConnectionRequest`: 创建连接时用户可见的字段
   - `UpdateConnectionRequest`: 更新连接时用户可见的字段
   - 服务端字段(id, createdBy, createdAt, updatedAt)对用户不可见

2. **服务端字段保护**: 创建和更新接口会自动处理以下字段，防止用户恶意修改：
   - `id`: 由数据库自动生成
   - `createdBy`: 自动设置为当前登录用户
   - `createdAt`: 由数据库自动生成
   - `updatedAt`: 由数据库自动更新

3. **权限验证**: 所有数据库连接操作都会验证用户权限
   - 管理员可以访问所有连接
   - 普通用户只能访问自己有权限的连接
   - 用户只能修改或删除自己创建的连接

### 添加新的API

1. 在 `controller` 包中创建新的控制器类
2. 添加 `@Api` 和 `@Controller` 注解
3. 为每个方法添加 `@ApiOperation` 注解
4. 对于需要认证的接口，添加 `@ApiImplicitParams` 和 `@ApiResponses` 注解
5. 在服务端逻辑中处理好字段保护和权限验证

### 测试

项目提供了多种测试方式：

#### 单元测试

```bash
mvn test
```

#### MCP客户端测试

```bash
# 运行MCP客户端测试
java -cp target/classes com.jdbcmcp.mcp.McpClientTest

# 运行HTTP MCP测试
java -cp target/classes com.jdbcmcp.test.HttpMcpTest

# 运行功能测试
java -cp target/classes com.jdbcmcp.test.McpFunctionTest
```

#### 手动测试

1. 启动服务：
```bash
mvn clean package
java -jar target/jdbc-mcp-server-1.0.0.jar
```

2. 获取管理员token：
```bash
curl -X POST http://localhost:8081/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'
```

3. 测试MCP工具：
```bash
curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_token>" \
  -d '{
    "tool": "ping",
    "params": {}
  }'
```

1. 在 `mcp` 包中创建新的工具类
2. 添加 `@AiMapping` 注解
3. 实现具体的工具逻辑
4. 在 `OpenApiConfig` 中添加扫描路径

## 安全说明

- 使用JWT进行用户认证
- 密码使用BCrypt加密存储
- 支持基于角色的权限控制
- 数据库连接信息加密存储
- SQL注入防护

## 快速参考

### 常用命令

```bash
# 构建项目
mvn clean package -DskipTests

# 运行应用
java -jar target/jdbc-mcp-server-1.0.0.jar

# 获取管理员token
curl -X POST http://localhost:8081/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

# 测试MCP连接
curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"tool": "ping", "params": {}}'
```

### 默认端口

- 应用端口: 8081
- MCP端点: http://localhost:8081/mcp
- API文档: http://localhost:8081/doc.html

### 默认账户

- 用户名: admin
- 密码: admin123
- 角色: admin

### MCP工具列表

| 工具名称 | 描述 | 必需参数 |
|---------|------|----------|
| ping | 测试服务器连接 | 无 |
| getAvailableConnections | 获取可用连接列表 | 无 |
| getDatabases | 获取数据库列表 | connectionId |
| getTables | 获取表列表 | connectionId, databaseName |
| getColumns | 获取字段信息 | connectionId, tableName |
| executeSql | 执行SQL查询 | connectionId, sql |

### 支持的数据库类型

- MySQL
- PostgreSQL  
- Oracle
- DB2
- Vertica
- Hive
- ClickHouse

## 故障排除

### 端口冲突

如果8080端口被占用，可以在 `app.properties` 中修改端口：
```properties
server.port=8081
```


### 数据库连接问题

确保数据库驱动已正确添加到 `pom.xml`，并且连接字符串格式正确。

### 认证失败

检查请求头中的 `Authorization` 格式是否正确：
```
Authorization: Bearer <token>
```

### MCP工具调用失败

1. 确保MCP服务器正常运行
2. 检查认证token是否有效
3. 验证连接ID是否存在
4. 检查SQL语法是否正确

## 贡献指南

欢迎提交Issue和Pull Request来改进这个项目。

## 许可证

Apache License 2.0 - 详见 [LICENSE](LICENSE) 文件