mcp-database-server

HuangHaohang/mcp-database-server

3.2

If you are the rightful owner of mcp-database-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Database MCP Server is a Java Spring Boot-based server that provides database access capabilities to AI models through the Model Context Protocol (MCP).

Tools
5
Resources
0
Prompts
0

Database MCP Server

一个基于 Java Spring Boot 的数据库 MCP (Model Context Protocol) 服务器，为 AI 模型提供数据库访问能力。

🚀 项目简介

Database MCP Server 是一个实现了 MCP 协议的数据库访问服务器，允许 AI 模型通过标准化的接口安全地访问和操作数据库。

核心特性

  • 🔐 安全访问: 内置 SQL 注入防护和危险操作检测
  • 🌐 WebSocket 支持: 实时双向通信
  • 🛠️ 多种工具: 提供 SQL 执行、表结构查询等工具
  • 📊 元数据访问: 支持数据库架构和统计信息查询
  • 🔧 REST API: 提供完整的管理接口
  • 📈 性能优化: 内置查询优化和索引建议

🏗️ 技术架构

  • Java 11: 现代 Java 特性
  • Spring Boot 3.3.6: 微服务框架
  • Spring Data JPA: 数据访问层
  • WebSocket: 实时通信
  • MySQL: 数据库支持
  • Maven: 项目构建

📦 项目结构

mcp-database-server/
├── src/main/java/com/hhh/mcp/
│   ├── McpDatabaseServerApplication.java    # 主启动类
│   ├── config/
│   │   └── WebSocketConfig.java             # WebSocket 配置
│   ├── controller/
│   │   └── McpController.java               # REST API 控制器
│   ├── entity/
│   │   └── DatabaseConnection.java          # 数据库连接实体
│   ├── protocol/
│   │   ├── McpMessage.java                  # MCP 消息协议
│   │   └── McpError.java                    # MCP 错误定义
│   ├── repository/
│   │   └── DatabaseConnectionRepository.java # 数据访问层
│   ├── service/
│   │   ├── DatabaseService.java             # 数据库服务
│   │   └── McpService.java                  # MCP 协议服务
│   ├── util/
│   │   ├── SqlUtils.java                    # SQL 工具类
│   │   └── DatabaseUtils.java               # 数据库工具类
│   └── websocket/
│       └── McpWebSocketHandler.java         # WebSocket 处理器
├── src/main/resources/
│   └── application.yml                      # 应用配置
└── pom.xml                                  # Maven 配置

🛠️ 安装和配置

1. 环境要求

  • Java 11 或更高版本
  • Maven 3.6+
  • MySQL 8.0+

2. 数据库配置

修改 src/main/resources/application.yml 中的数据库连接信息：

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

3. 编译和运行

# 编译项目
mvn clean compile

# 运行项目
mvn spring-boot:run

服务器将在 http://localhost:8080 启动。

🔌 MCP 协议接口

WebSocket 连接

连接地址: ws://localhost:8080/mcp

支持的工具 (Tools)

  1. execute_sql - 执行 SQL 语句

    {
  "name": "execute_sql",
  "arguments": {
    "sql": "SELECT * FROM users LIMIT 10",
    "params": ["param1", "param2"]
  }
}

  2. list_databases - 列出所有数据库

    {
  "name": "list_databases",
  "arguments": {}
}

  3. list_tables - 列出指定数据库的表

    {
  "name": "list_tables",
  "arguments": {
    "database": "test_db"
  }
}

  4. describe_table - 获取表结构

    {
  "name": "describe_table",
  "arguments": {
    "database": "test_db",
    "table": "users"
  }
}

  5. show_indexes - 显示表索引

    {
  "name": "show_indexes",
  "arguments": {
    "database": "test_db",
    "table": "users"
  }
}

支持的资源 (Resources)

  1. database://schema - 数据库完整架构
  2. database://status - 数据库连接状态

🌐 REST API

服务器状态

  • GET /api/mcp/status - 获取服务器状态

数据库连接管理

  • GET /api/mcp/connections - 获取所有连接
  • POST /api/mcp/connections - 创建新连接
  • PUT /api/mcp/connections/{id} - 更新连接
  • DELETE /api/mcp/connections/{id} - 删除连接
  • POST /api/mcp/connections/{id}/test - 测试连接

SQL 执行

  • POST /api/mcp/sql/execute - 执行 SQL 语句

数据库信息

  • GET /api/mcp/databases - 获取数据库列表
  • GET /api/mcp/databases/{db}/tables - 获取表列表
  • GET /api/mcp/databases/{db}/tables/{table}/structure - 获取表结构

🔒 安全特性

SQL 注入防护

  • 参数化查询
  • 危险操作检测
  • SQL 语法验证

访问控制

  • 禁止无条件 DELETE/UPDATE
  • 禁止 DROP/TRUNCATE 操作
  • 查询结果限制

错误处理

  • 详细的错误信息
  • 安全的错误响应
  • 操作日志记录

📊 监控和日志

应用监控

服务器提供详细的运行状态信息，包括：

  • 连接池状态
  • 查询执行统计
  • 错误率监控

日志配置

logging:
  level:
    com.hhh.mcp: INFO
    org.springframework.web.socket: DEBUG

🧪 测试

单元测试

mvn test

集成测试

mvn integration-test

WebSocket 测试

可以使用 WebSocket 客户端工具连接到 ws://localhost:8080/mcp 进行测试。

🚀 部署

Docker 部署

FROM openjdk:11-jre-slim
COPY target/mcp-database-server-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

生产环境配置

server:
  port: 8080
spring:
  profiles:
    active: prod
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000

🤝 贡献指南

  1. Fork 项目
  2. 创建特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 文件了解详情。

🆘 支持

如果您遇到问题或有疑问，请：

  1. 查看 Issues 页面
  2. 创建新的 Issue 描述问题
  3. 联系维护者

🔄 更新日志

v1.0.0 (2024-01-XX)

  • 初始版本发布
  • 实现基础 MCP 协议支持
  • 添加数据库连接管理
  • 提供 REST API 接口
  • 实现安全防护机制

注意: 这是一个教学项目，用于演示如何构建 MCP 服务器。在生产环境中使用前，请确保进行充分的安全测试和配置。