jj-multi-database-mcp 0.3.1
Multi-database MCP server supporting SQL Server, Oracle, Redis and filesystem operations
Requires Python: >=3.8

﻿git push -u origin main# JJ MCP - 多数据库 MCP 服务器

一个全面的 MCP (Model Context Protocol) 服务器，支持多种数据库和文件系统操作。

## 功能特性

- **SQL Server 支持**: 查询、执行、表结构获取等完整功能
- **Oracle 数据库支持**: 完整的 Oracle 数据库操作支持
- **MySQL 数据库支持**: 完整的 MySQL 数据库操作支持
- **Redis 支持**: 基本的 Redis 操作（get、set、delete、keys 等）
- **文件系统操作**: 安全的文件读写和目录操作
- **安全控制**: 路径访问控制、文件扩展名限制等
- **环境变量配置**: 灵活的配置管理
- **跨平台支持**: Windows、Linux、macOS
- **🔥 智能重连机制**: 数据库服务启动后自动检测并连接
- **🛡️ 高可用性**: 断线重连、健康检查、优雅降级
- **📊 系统监控**: 实时性能监控、资源使用统计
- **🔄 故障恢复**: 断路器模式、自动重试、错误隔离
- **🧵 线程安全**: 并发访问保护、资源管理
- **⚡ 高性能**: 500+ TPS，90%+ 成功率，零内存泄漏

## 安装

### 🚀 快速安装向导

```bash
# 下载并运行交互式安装向导
curl -O https://raw.githubusercontent.com/ppengit/jj-multi-database-mcp/main/quick_install.py
python quick_install.py
```

### 基础安装

```bash
pip install jj-multi-database-mcp
```

### 数据库支持安装（按需）

根据您需要使用的数据库，安装相应的扩展：

#### SQL Server 支持
```bash
# 安装 SQL Server 支持
pip install jj-multi-database-mcp[sqlserver]

# 需要安装 ODBC Driver for SQL Server
# 下载地址: https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server
```

#### Oracle 支持
```bash
# 安装 Oracle 支持
pip install jj-multi-database-mcp[oracle]

# 可能需要安装 Oracle Instant Client
# 下载地址: https://www.oracle.com/database/technologies/instant-client.html
```

#### MySQL 支持
```bash
# 安装 MySQL 支持
pip install jj-multi-database-mcp[mysql]
```

#### Redis 支持
```bash
# 安装 Redis 支持
pip install jj-multi-database-mcp[redis]
```

#### 多数据库组合安装
```bash
# 同时安装多个数据库支持（推荐方式）
pip install jj-multi-database-mcp[sqlserver,mysql,redis]

# 其他常用组合示例
pip install jj-multi-database-mcp[mysql,redis]           # MySQL + Redis
pip install jj-multi-database-mcp[sqlserver,oracle]     # SQL Server + Oracle
pip install jj-multi-database-mcp[mysql,oracle,redis]   # MySQL + Oracle + Redis
```

#### 安装所有数据库支持
```bash
# 一次性安装所有数据库支持
pip install jj-multi-database-mcp[all-databases]
```

#### 验证安装
```bash
# 下载并运行验证脚本
curl -O https://raw.githubusercontent.com/ppengit/jj-multi-database-mcp/main/verify_installation.py
python verify_installation.py
```

### 📋 常用安装组合表

| 使用场景 | 安装命令 | 包含功能 |
|---------|---------|---------|
| **Web开发** | `pip install jj-multi-database-mcp[mysql,redis]` | MySQL + Redis + 文件系统 |
| **企业应用** | `pip install jj-multi-database-mcp[sqlserver,redis]` | SQL Server + Redis + 文件系统 |
| **数据分析** | `pip install jj-multi-database-mcp[mysql,oracle]` | MySQL + Oracle + 文件系统 |
| **微服务** | `pip install jj-multi-database-mcp[mysql,redis]` | MySQL + Redis + 文件系统 |
| **全栈开发** | `pip install jj-multi-database-mcp[all-databases]` | 所有数据库 + 文件系统 |
| **仅文件操作** | `pip install jj-multi-database-mcp` | 仅文件系统操作 |

### 🎯 您的具体需求示例

**问题**: 我只需要 SQL Server + Redis + MySQL，怎么安装？
```bash
pip install jj-multi-database-mcp[sqlserver,redis,mysql]
```

**问题**: 我只需要 MySQL，怎么安装？
```bash
pip install jj-multi-database-mcp[mysql]
```

**问题**: 我需要所有数据库支持，怎么安装？
```bash
pip install jj-multi-database-mcp[all-databases]
```

**注意**: 如果不安装某个数据库的扩展，对应的数据库功能将不可用，但不会影响其他功能的正常使用。

## 配置

### 1. 创建配置文件

复制示例配置文件并修改：

```bash
cp .env.example .env
```

### 2. 配置数据库连接

编辑 `.env` 文件，启用并配置需要的数据库：

```env
# SQL Server
SQLSERVER_ENABLED=true
SQLSERVER_HOST=localhost
SQLSERVER_PORT=1433
SQLSERVER_DATABASE=mydb
SQLSERVER_USERNAME=myuser
SQLSERVER_PASSWORD=mypass

# Oracle
ORACLE_ENABLED=true
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_SERVICE_NAME=ORCL
ORACLE_USERNAME=myuser
ORACLE_PASSWORD=mypass

# MySQL
MYSQL_ENABLED=true
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_DATABASE=mydb
MYSQL_USERNAME=myuser
MYSQL_PASSWORD=mypass

# Redis
REDIS_ENABLED=true
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=mypass
```

### 3. 文件系统安全配置

```env
# 限制访问路径（推荐用于生产环境）
FS_ALLOWED_PATHS=/home/user/data,/tmp

# 限制文件类型
FS_ALLOWED_EXTENSIONS=.txt,.py,.json,.csv

# 禁用删除操作（推荐用于生产环境）
FS_ENABLE_DELETE=false
```

### 4. 云数据库配置示例

#### 阿里云 RDS for MySQL
```env
MYSQL_ENABLED=true
MYSQL_HOST=rm-xxxxxxxx.mysql.rds.aliyuncs.com
MYSQL_PORT=3306
MYSQL_DATABASE=mydb
MYSQL_USERNAME=myuser
MYSQL_PASSWORD=mypass
MYSQL_USE_SSL=true
MYSQL_RDS_INSTANCE_ID=rm-xxxxxxxx
MYSQL_REGION=cn-hangzhou
```

#### Azure SQL Database
```env
SQLSERVER_ENABLED=true
SQLSERVER_HOST=myserver.database.windows.net
SQLSERVER_PORT=1433
SQLSERVER_DATABASE=mydb
SQLSERVER_USERNAME=myuser@myserver
SQLSERVER_PASSWORD=mypass
SQLSERVER_ENCRYPT=true
SQLSERVER_TRUST_CERT=false
SQLSERVER_AUTHENTICATION=ActiveDirectoryPassword
```

#### AWS RDS for MySQL
```env
MYSQL_ENABLED=true
MYSQL_HOST=mydb.xxxxxxxx.us-east-1.rds.amazonaws.com
MYSQL_PORT=3306
MYSQL_DATABASE=mydb
MYSQL_USERNAME=myuser
MYSQL_PASSWORD=mypass
MYSQL_USE_SSL=true
MYSQL_REGION=us-east-1
```

## 使用方法

### 启动服务器

JJ MCP 支持两种运行方式：

#### 方式1：安装后使用（推荐）
```bash
# 安装后直接运行
jj-multi-database-mcp
# 或者使用短名称
jj-mcp

# 或者使用 Python 模块
python -m jj_mcp
```

#### 方式2：从源码运行
```bash
# 克隆仓库
git clone https://github.com/ppengit/jj-multi-database-mcp
cd jj-multi-database-mcp

# 安装依赖
pip install -e .

# 运行服务器
python -m jj_mcp
```

### MCP 客户端配置

#### 使用已安装的包：
```json
{
  "mcpServers": {
    "jj-multi-db": {
      "command": "jj-multi-database-mcp",
      "env": {
        "SQLSERVER_ENABLED": "true",
        "MYSQL_ENABLED": "true"
      }
    }
  }
}
```

#### 使用源码：
```json
{
  "mcpServers": {
    "jj-multi-db": {
      "command": "python",
      "args": ["-m", "jj_mcp"],
      "cwd": "/path/to/jj-multi-database-mcp"
    }
  }
}
```

## MCP 客户端配置

### Claude Desktop 配置

在 Claude Desktop 中使用，需要编辑配置文件：

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

#### 基础配置示例：
```json
{
  "mcpServers": {
    "jj-multi-database-mcp": {
      "command": "jj-multi-database-mcp",
      "env": {
        "MCP_LOG_LEVEL": "INFO",
        "FS_ALLOWED_PATHS": "C:\\Users\\YourName\\Documents,D:\\Projects",
        "FS_ALLOWED_EXTENSIONS": ".txt,.py,.json,.csv,.md"
      }
    }
  }
}
```

#### 启用 SQL Server 的配置：
```json
{
  "mcpServers": {
    "jj-multi-database-mcp": {
      "command": "jj-multi-database-mcp",
      "env": {
        "SQLSERVER_ENABLED": "true",
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_DATABASE": "MyDatabase",
        "SQLSERVER_USERNAME": "sa",
        "SQLSERVER_PASSWORD": "YourPassword123",
        "SQLSERVER_TRUST_CERT": "true",
        "SQLSERVER_ENCRYPT": "false"
      }
    }
  }
}
```

#### 启用 MySQL（阿里云 RDS）的配置：
```json
{
  "mcpServers": {
    "jj-multi-database-mcp": {
      "command": "jj-multi-database-mcp",
      "env": {
        "MYSQL_ENABLED": "true",
        "MYSQL_HOST": "rm-xxxxxxxx.mysql.rds.aliyuncs.com",
        "MYSQL_PORT": "3306",
        "MYSQL_DATABASE": "mydb",
        "MYSQL_USERNAME": "myuser",
        "MYSQL_PASSWORD": "mypassword",
        "MYSQL_USE_SSL": "true",
        "MYSQL_RDS_INSTANCE_ID": "rm-xxxxxxxx",
        "MYSQL_REGION": "cn-hangzhou"
      }
    }
  }
}
```

#### 多数据库完整配置：
```json
{
  "mcpServers": {
    "jj-multi-database-mcp": {
      "command": "jj-multi-database-mcp",
      "env": {
        "MCP_LOG_LEVEL": "INFO",

        "SQLSERVER_ENABLED": "true",
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_DATABASE": "MyDB",
        "SQLSERVER_USERNAME": "sa",
        "SQLSERVER_PASSWORD": "Password123",

        "MYSQL_ENABLED": "true",
        "MYSQL_HOST": "localhost",
        "MYSQL_DATABASE": "testdb",
        "MYSQL_USERNAME": "root",
        "MYSQL_PASSWORD": "password",

        "ORACLE_ENABLED": "true",
        "ORACLE_HOST": "localhost",
        "ORACLE_SERVICE_NAME": "ORCL",
        "ORACLE_USERNAME": "system",
        "ORACLE_PASSWORD": "password",

        "REDIS_ENABLED": "true",
        "REDIS_HOST": "localhost",
        "REDIS_PORT": "6379",
        "REDIS_PASSWORD": "",

        "FS_ALLOWED_PATHS": "*",
        "FS_ALLOWED_EXTENSIONS": "*",
        "FS_ENABLE_WRITE": "true",
        "FS_ENABLE_DELETE": "false"
      }
    }
  }
}
```

#### 从源码运行的配置：
```json
{
  "mcpServers": {
    "jj-multi-database-mcp": {
      "command": "python",
      "args": ["-m", "jj_mcp"],
      "cwd": "D:\\Projects\\jj-multi-database-mcp",
      "env": {
        "MYSQL_ENABLED": "true",
        "MYSQL_HOST": "localhost",
        "MYSQL_DATABASE": "testdb",
        "MYSQL_USERNAME": "root",
        "MYSQL_PASSWORD": "password"
      }
    }
  }
}
```

### 其他 MCP 客户端

对于其他支持 MCP 的客户端，配置方式类似，主要是指定：
- **命令**: `jj-multi-database-mcp`
- **环境变量**: 数据库连接参数
- **工作目录**: （可选）如果从源码运行

### 配置验证

配置完成后，可以使用验证脚本检查：
```bash
python verify_installation.py
```

### MCP 工具

服务器提供以下工具：

#### SQL Server 工具
- `sql_query_mcp-sqlserver-filesystem`: 执行 SELECT 查询
- `sql_execute_mcp-sqlserver-filesystem`: 执行 INSERT/UPDATE/DELETE
- `get_table_schema_mcp-sqlserver-filesystem`: 获取表结构
- `list_tables_mcp-sqlserver-filesystem`: 列出所有表

#### Oracle 工具
- `oracle_query`: 执行 Oracle SELECT 查询
- `oracle_execute`: 执行 Oracle INSERT/UPDATE/DELETE
- `oracle_table_schema`: 获取 Oracle 表结构
- `oracle_list_tables`: 列出 Oracle 表

#### MySQL 工具
- `mysql_query`: 执行 MySQL SELECT 查询
- `mysql_execute`: 执行 MySQL INSERT/UPDATE/DELETE
- `mysql_table_schema`: 获取 MySQL 表结构
- `mysql_list_tables`: 列出 MySQL 表

#### Redis 工具
- `redis_get`: 获取键值
- `redis_set`: 设置键值
- `redis_delete`: 删除键
- `redis_keys`: 获取匹配的键列表
- `redis_exists`: 检查键是否存在

#### 文件系统工具
- `read_file_mcp-sqlserver-filesystem`: 读取文件内容
- `write_file_mcp-sqlserver-filesystem`: 写入文件内容
- `list_directory_mcp-sqlserver-filesystem`: 列出目录内容

## 前置条件

### SQL Server
- 安装 ODBC Driver for SQL Server
- 确保 SQL Server 允许远程连接
- 配置正确的防火墙规则
- 支持 Azure SQL Database（使用 ActiveDirectory 认证）
- 支持高级连接选项（MARS、加密、应用程序意图等）

### Oracle
- 安装 Oracle Instant Client（如果使用 thick 模式）
- 配置 TNS 或使用 Easy Connect 字符串
- 确保网络连接正常

### MySQL
- MySQL 服务器运行中
- 配置正确的用户权限
- 确保网络连接和端口开放
- **支持云服务**：
  - 阿里云 RDS for MySQL
  - AWS RDS for MySQL
  - 腾讯云 CDB for MySQL
  - 其他兼容 MySQL 协议的云数据库
- 支持 SSL/TLS 加密连接
- 支持自定义字符集和排序规则

### Redis
- Redis 服务器运行中
- 配置正确的认证信息（如果启用）

## 🔥 智能重连机制

### 动态数据库连接

JJ MCP 具有智能的动态重连机制，解决数据库服务延迟启动的问题：

#### ✨ **核心特性**：
- **即时检测**: 每次数据库操作都会检查连接状态
- **智能重连**: 数据库服务启动后立即自动连接
- **退避算法**: 避免频繁重连影响性能
- **线程安全**: 支持并发访问

#### 🎯 **使用场景**：
```bash
# 场景1: 先启动MCP，后启动数据库
1. 启动 jj-multi-database-mcp
2. 此时数据库服务未启动，操作会失败但不会崩溃
3. 启动数据库服务（MySQL/SQL Server/Oracle）
4. 下次数据库操作时会自动检测到服务可用并立即连接
5. 无需重启MCP服务器！

# 场景2: 数据库服务重启
1. 数据库服务重启期间，MCP会检测到连接断开
2. 数据库服务恢复后，MCP会自动重新连接
3. 用户无感知，操作继续正常进行
```

#### 📊 **智能退避策略**：
- **首次失败**: 立即重试
- **后续失败**: 1s → 2s → 4s → 8s → ... → 最大5分钟
- **随机抖动**: 避免多个实例同时重连
- **成功后重置**: 连接成功后重置退避计数器

## 故障排除

### 常见问题

1. **SQL Server 连接失败**
   - 检查 ODBC 驱动是否正确安装
   - 验证连接字符串和认证信息
   - 确认 SQL Server 允许远程连接

2. **Oracle 连接失败**
   - 检查 Oracle 客户端库是否安装
   - 验证 TNS 配置或连接字符串
   - 确认网络连接和端口开放

3. **Redis 连接失败**
   - 检查 Redis 服务是否运行
   - 验证主机、端口和认证信息
   - 检查防火墙设置

4. **文件系统权限错误**
   - 检查路径访问权限
   - 验证 `FS_ALLOWED_PATHS` 配置
   - 确认文件扩展名在允许列表中

### 日志调试

启用调试日志：

```env
MCP_LOG_LEVEL=DEBUG
```

## 安全注意事项

1. **生产环境配置**
   - 限制文件系统访问路径
   - 禁用不必要的数据库功能
   - 使用强密码和加密连接

2. **网络安全**
   - 配置防火墙规则
   - 使用 VPN 或专用网络
   - 启用数据库加密连接

3. **访问控制**
   - 使用最小权限原则
   - 定期审查配置
   - 监控访问日志

## 许可证

MIT License

## 作者

PJ (peng.it@qq.com)

## 贡献

欢迎提交 Issue 和 Pull Request！