# DatabaseMCP 数据库操作服务器

[![NuGet](https://img.shields.io/nuget/v/DatabaseMcpServer.svg)](https://www.nuget.org/packages/DatabaseMcpServer)
[![.NET Tool](https://img.shields.io/badge/.NET%20Tool-3.7.0-blue.svg)](https://www.nuget.org/packages/DatabaseMcpServer)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[🇺🇸 English](README_EN.md) | [🇨🇳 中文](README.md) | [🌐 官网](https://databasemcp.ttcc.online/)

 一个功能强大的数据库操作 MCP (Model Context Protocol) 服务器，聚焦 **19 种常用数据库类型**（主流 + 特定场景 + 国产化/信创），支持 **单实例多数据库动态切换**，让 AI 助手能够安全、便捷地执行数据库操作。

## ✨ 核心特性

- 🗄️ **多数据库支持** - 覆盖 17 种常用数据库（MySQL/PG/SQLServer/Oracle/MongoDB + SQLite/ClickHouse/TiDB/OceanBase + 达梦/人大金仓/华为 GaussDB/PolarDB/Vastbase/瀚高/神通/GoldenDB）
- 🔄 **单实例多数据库** - 一个 MCP Server 实例可配置和动态切换多个数据库连接
- 🔒 **安全防护** - 危险操作检测 + SQL 注入防护 + 敏感信息保护
- ⚡ **高性能优化** - SqlSugarScope 连接池复用 + 数据库特定优化 + 自动性能调优
- 🔧 **灵活配置** - 支持 JSON 配置文件，轻松管理多数据库连接
- 💾 **完整功能** - 50+ MCP 工具（当前约 55 个），涵盖查询、操作、架构管理、健康检查等
- 🚀 **生产就绪** - 支持事务、批量操作、存储过程、自动重连
- 📦 **.NET Global Tool** - 简单安装，一键部署
- 🌐 **跨平台** - Windows、macOS、Linux 全面支持

## 🗄️ 支持的数据库类型

### 🔥 一线最常用
- **MySQL** (默认)
- **PostgreSQL**
- **SQL Server**
- **Oracle**
- **MongoDB**

### 📊 特定场景常用
- **SQLite**
- **ClickHouse**
- **TiDB**
- **OceanBase**
- ~~IBM DB2~~（已移除）
- ~~SAP HANA~~（已移除）

### 🇨🇳 国产化/信创
- **达梦数据库** (dm)
- **人大金仓** (kdbndp/kingbase)
- **华为 GaussDB / OpenGauss**
- **PolarDB** (polardb)
- **海量数据库** (vastbase)
- **瀚高数据库** (hg)
- **神通数据库** (oscar)
- **GoldenDB** (goldendb)

## 🚀 快速开始

### 第一步：安装 .NET Global Tool

```bash
# 安装最新版本
dotnet tool install --global DatabaseMcpServer

# 验证安装（CLI 本身没有 --version 参数；传入会得到退出码 2）
dotnet tool list --global | Select-String databasemcpserver
```

### 第二步：创建数据库配置文件

创建 `databases.json` 配置文件：

```json
{
  "enableMonitorConfig": false,
  "databases": [
    {
      "name": "default",
      "connectionString": "Server=localhost;Database=test;Uid=root;Pwd=123456;",
      "dbType": "MySql",
      "description": "默认数据库",
      "isDefault": true
    }
  ]
}
```

`enableMonitorConfig` 为可选根字段，默认 `false`。设为 `true` 后，长驻 MCP stdio / `-web` 会监听该文件，并在默认库变化时切换运行时当前库。优先级见下方[配置文件监听](#配置文件监听可选)。

> 💡 如果未在 MCP 客户端配置中设置 `DB_CONFIG_PATH`，stdio 模式会自动读取 `%USERPROFILE%/.database-mcp/databases.json`；CLI / `-web` 会额外在当前目录检查 `./databases.json` 和 `./local-databases.json`。显式设置仍是推荐做法。

### 第三步：配置 MCP 客户端

创建 `mcp.json` 配置文件（VS Code: `.vscode/mcp.json`）:

```json
{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer",
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}
```

### 第四步：测试连接并执行查询

重启 IDE 后，在 AI 助手中测试：

```
"测试数据库连接"
```

系统返回：
```json
{
  "success": true,
  "connected": true,
  "databaseType": "MySql"
}
```

## 💻 命令行模式（CLI）

从当前版本开始，`DatabaseMcpServer` 在保留原有 MCP stdio 模式的同时，也支持直接从命令行做两类事情：

- **无参数**：启动 stdio MCP server（兼容现有 MCP 客户端配置）
- **`-web`**：启动 localhost Web 配置管理页，并默认自动打开浏览器
- **`tool` 子命令**：直接调用已暴露的 MCP tool
- **`init` / `config` 子命令**：初始化并维护本地 `databases.json`

### 基本用法

```bash
# 启动本地 Web 配置页（默认自动打开浏览器）
DatabaseMcpServer -web
DatabaseMcpServer -web --config "D:\config\databases.json" --no-browser

# 启动 stdio MCP / -web，并在本进程启用或关闭配置文件监听
DatabaseMcpServer --enable-monitor-config
DatabaseMcpServer --enable-monitor-config true
DatabaseMcpServer --enable-monitor-config false -web --no-browser
DatabaseMcpServer -web --enable-monitor-config true --no-browser

# 初始化默认配置文件（默认写到 %USERPROFILE%/.database-mcp/databases.json）
DatabaseMcpServer init

# 查看 / 管理本地连接配置
DatabaseMcpServer config list
DatabaseMcpServer config presets
DatabaseMcpServer config preset --db-type Sqlite
DatabaseMcpServer config create --from-preset Sqlite --name sqlite-local --connection-string "Data Source=./data/local.db;Cache=Shared;Mode=ReadWriteCreate;" --description "local sqlite" --set-default
DatabaseMcpServer config create --from-preset Sqlite --name sqlite-preview --print-only
DatabaseMcpServer config add --name sqlite-local --db-type Sqlite --connection-string "Data Source=./data/local.db;Cache=Shared;Mode=ReadWriteCreate;" --set-default
DatabaseMcpServer config rename --name sqlite-local --new-name sqlite-dev
DatabaseMcpServer config update --name sqlite-dev --description "dev sqlite" --set-default
DatabaseMcpServer config validate
DatabaseMcpServer config clone --name sqlite-dev --new-name sqlite-ci
DatabaseMcpServer config doctor
DatabaseMcpServer config export --output ".\\backup-databases.json"
DatabaseMcpServer config import --input ".\\backup-databases.json" --config "D:\config\databases.json" --force

# 列出所有可调用的 tool
DatabaseMcpServer tool list

# 查看某个 tool 的帮助
DatabaseMcpServer tool help switch_database

# 直接调用 tool
DatabaseMcpServer tool list_databases --config "D:\config\databases.json"
DatabaseMcpServer tool get_table_schema --table-name users --config "D:\config\databases.json"
```

### 参数规则

- `-web` 主要用于**本地可视化配置管理**
  - 默认绑定 `localhost / 127.0.0.1`，不对公网暴露
  - 默认沿用 CLI 配置解析顺序：`--config -> ./databases.json -> ./local-databases.json -> DB_CONFIG_PATH -> %USERPROFILE%/.database-mcp/databases.json`
  - 如果没有找到现有配置文件，则回退到 `%USERPROFILE%/.database-mcp/databases.json` 作为可写目标
  - 页面同时管理两套状态：`databases.json` 中的默认连接，以及 `%USERPROFILE%/.database-mcp/cli-state.json` 中的当前连接
  - `--port <number>` 可显式指定端口；不传则自动分配可用端口
  - `--no-browser` 可禁用自动打开浏览器
  - `--enable-monitor-config true|false` 可在本进程强制开启或关闭 `databases.json` 监听，优先级高于环境变量和配置文件
- `init` / `config` 主要用于**本地配置管理**
  - 默认操作 `%USERPROFILE%/.database-mcp/databases.json`
  - 可以用 `--config <path>` 临时覆盖目标配置文件
  - `config use` / `config set-default` 用来切换默认连接（写回 `databases.json`）
  - `config rename` / `config update` 用来演进已有连接
  - `config validate` 用来做配置文件层校验（不是连通性测试）
  - `config clone` 用来快速复制连接
  - `config presets` / `config preset` 用来查看内置连接模板
  - `config create --from-preset` 用来直接基于模板生成连接骨架，也可顺手覆盖连接串/描述
  - `config update --clear-description` 用来显式清空说明
  - `--enable-dangerous-operations true|false` 可在 `config create/add/update` 中写入危险操作开关（默认 `false`）
  - `config doctor` 用来做诊断，默认会测试各连接连通性，并给出修复建议；`--summary-only` 适合脚本
  - `config export` / `config import` 用来备份和迁移配置文件
- tool 名称与 MCP 中保持一致，使用 `snake_case`
  - 例如：`list_databases`、`get_table_schema`、`execute_command`
- tool 参数统一映射为 `kebab-case` 选项
  - 例如：`databaseName -> --database-name`
  - 例如：`initialDelayMs -> --initial-delay-ms`
- `tool switch_database` 用来切换**当前连接**
  - CLI 下会按“已解析 config 路径”持久化当前连接到 `%USERPROFILE%/.database-mcp/cli-state.json`
  - 不会修改 `databases.json` 里的默认连接
  - 后续 `tool get_current_database` / `tool list_databases` / 查询类命令都会继续使用这个当前连接
  - 只有在没有已保存当前连接，或保存的连接已失效时，才会回退到默认连接
- CLI 全局选项：
  - `--config <path>`：本次调用临时指定配置文件
  - `--yes`：执行写操作 / 高风险 schema tool 时必须显式确认
  - `--help`：显示帮助

### tool 模式下的配置文件查找顺序

如果执行的是 `DatabaseMcpServer tool ...`，且没有显式传 `--config`，CLI 会按以下顺序查找数据库配置：

1. 当前目录 `./databases.json`
2. 当前目录 `./local-databases.json`
3. 环境变量 `DB_CONFIG_PATH`
4. 用户目录 `%USERPROFILE%/.database-mcp/databases.json`

### 高风险命令确认

以下写操作 / 高风险命令必须追加 `--yes`：

```bash
DatabaseMcpServer tool drop_table --table-name users --config "D:\config\databases.json" --yes
DatabaseMcpServer tool execute_command --sql "delete from users where id = 1" --config "D:\config\databases.json" --yes
```

CLI 模式下，命令结果 JSON 输出到 `stdout`，帮助和日志输出到 `stderr`，便于脚本集成。
另外，`tool switch_database` 与 `config use` 语义不同：前者切换并持久化“当前连接”，后者修改配置文件中的“默认连接”。

详细命令说明见：

- [CLI 命令文档](Doc/cli.md)

## 📦 安装方式

### 方式 1：.NET Global Tool（推荐）

**安装**：
```bash
dotnet tool install --global DatabaseMcpServer
# 更新：dotnet tool update --global DatabaseMcpServer
```

**MCP 配置**：
```json
{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer",
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}
```

### 方式 2：dnx 命令

**安装**：
```bash
dnx DatabaseMcpServer@3.6.5 --yes
```

**MCP 配置**：
```json
{
  "mcpServers": {
    "database": {
      "command": "dnx",
      "args": ["DatabaseMcpServer@3.6.5", "--yes"],
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}
```

### 方式 3：本地源码运行

**运行**：
```bash
git clone https://github.com/ttcc666/DatabaseMcpServer.git
cd DatabaseMcpServer
# .NET 9
dotnet run --framework net9.0

# .NET 10
dotnet run --framework net10.0
```

**MCP 配置**：
```json
{
  "mcpServers": {
    "database-net9": {
      "command": "dotnet",
      "args": ["run", "--framework", "net9.0", "--project", "path/to/DatabaseMcpServer"],
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    },
    "database-net10": {
      "command": "dotnet",
      "args": ["run", "--framework", "net10.0", "--project", "path/to/DatabaseMcpServer"],
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}
```

## ⚙️ 配置指南

DatabaseMcpServer 2.0.0 统一使用 JSON 配置文件管理数据库连接。

### 配置文件方式（推荐；未设置时自动发现）

通过环境变量 `DB_CONFIG_PATH` 指定配置文件的**绝对路径**：

> **自动发现优先级**：
>
> - **stdio 模式**：`DB_CONFIG_PATH` → `%USERPROFILE%/.database-mcp/databases.json`（不读取当前目录，避免 MCP 客户端目录下的零散文件被误读）。
> - **CLI / `-web` 模式**：`--config` → `./databases.json` → `./local-databases.json` → `DB_CONFIG_PATH` → `%USERPROFILE%/.database-mcp/databases.json`。
>
> 显式设置 `DB_CONFIG_PATH` 仍是推荐做法。

**MCP 配置示例：**

```json
{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer",
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}
```

当 `databases.json` 内容更新后，可以直接调用 `reload_database_config`，让 MCP 在不重启进程的情况下重新读取配置并刷新连接缓存。

**配置文件格式 (databases.json)：**

```json
{
  "enableMonitorConfig": false,
  "databases": [
    {
      "name": "mysql-main",
      "connectionString": "Server=localhost;Database=myapp;User=root;Password=123456;",
      "dbType": "MySql",
      "description": "MySQL 主库",
      "isDefault": true,
      "enableDangerousOperations": false,
      "optimizationSettings": {
        "enableCache": "true",
        "batchSize": "1000"
      }
    },
    {
      "name": "postgres-analytics",
      "connectionString": "Host=localhost;Database=analytics;Username=postgres;Password=123456;",
      "dbType": "PostgreSQL",
      "description": "PostgreSQL 分析库",
      "optimizationSettings": {
        "autoToLower": "true",
        "enableIlike": "true"
      }
    }
  ]
}
```

根级字段 `enableMonitorConfig` 可写入配置文件，控制长驻 MCP stdio / `-web` 是否监听该文件。省略时视为 `false`。

### 配置文件监听（可选）

长驻进程（MCP stdio / `-web`）可以监听 `databases.json`：文件里的默认库变化时，运行时当前库会跟着切换。一次性 `tool` / `config` 命令不会启用监听。

可通过以下来源配置，**优先级从高到低**：

| 优先级 | 来源 | 说明 |
| --- | --- | --- |
| 1（最高） | 启动参数 `--enable-monitor-config true\|false` | 仅对本进程生效，强制开启或关闭；不写回配置文件 |
| 2 | 环境变量 `ENABLE_MONITOR_CONFIG` | `true`/`false`（也接受 `1`/`0`/`yes`/`no`/`on`/`off`）；未设置时继续往下看 |
| 3 | 配置文件 `enableMonitorConfig` | `databases.json` 根字段；可直接编辑 JSON |
| 4（默认） | 未配置 | 关闭监听 |

示例：配置文件里写了 `"enableMonitorConfig": true`，但启动时带 `--enable-monitor-config false` 或环境变量 `ENABLE_MONITOR_CONFIG=false`，本进程仍不会监听。

**多数据库管理工具：**
- `list_databases` - 列出所有可用的数据库连接
- `switch_database` - 切换到指定的数据库
- `get_current_database` - 获取当前活动的数据库
- `test_connection_by_name` - 测试指定数据库的连接

**性能优化工具：**
- `health_check` - 对所有数据库连接执行健康检查（响应时间、连接状态）
- `test_connection_with_retry` - 带自动重试的连接测试（指数退避策略）

---

## 🌐 环境配置

### 可选环境变量
- `DB_CONFIG_PATH`: 数据库配置文件路径
  - 示例: `D:\config\databases.json`
  - 优先级: `环境变量DB_CONFIG_PATH` → `用户目录%USERPROFILE%/.database-mcp/databases.json`（stdio 模式）；CLI / `-web` 还会在当前目录查找 `./databases.json` 和 `./local-databases.json`
- `SEQ_SERVER_URL`: Seq 日志服务器地址（可选）
- `SEQ_API_KEY`: Seq API 密钥（可选）
- `DB_DDL_WHITELIST`: DDL 操作白名单（可选，分号分隔的正则表达式）
- `ENABLE_MONITOR_CONFIG`: 是否监听 `databases.json` 并让长驻 MCP / `-web` 跟随默认库变更（`true`/`false`，默认关闭）。也可在配置文件根级设置 `"enableMonitorConfig": true`。优先级：`--enable-monitor-config` > `ENABLE_MONITOR_CONFIG` > `enableMonitorConfig`。

### 数据库特定优化配置
从 2.0.0 版本开始，所有数据库特定优化配置都在 `databases.json` 的 `optimizationSettings` 中设置。

**详细配置文档**：
- [MySQL 配置指南](DatabaseSetting/MySQL.md)
- [PostgreSQL 配置指南](DatabaseSetting/PostgreSQL.md)
- [SQL Server 配置指南](DatabaseSetting/SQLServer.md)
- [Oracle 配置指南](DatabaseSetting/Oracle.md)
- [MongoDB 配置指南](DatabaseSetting/MongoDB.md)
- [SQLite 配置指南](DatabaseSetting/SQLite.md)
- [ClickHouse 配置指南](DatabaseSetting/ClickHouse.md)
- [TiDB 配置指南](DatabaseSetting/TiDB.md)
- [OceanBase 配置指南](DatabaseSetting/OceanBase.md)
- [达梦数据库配置指南](DatabaseSetting/DM.md)
- [人大金仓配置指南](DatabaseSetting/Kdbndp.md)
- [GaussDB 配置指南](DatabaseSetting/GaussDB.md)
- [PolarDB 配置指南](DatabaseSetting/PolarDB.md)
- [Vastbase 配置指南](DatabaseSetting/Vastbase.md)
- [瀚高数据库配置指南](DatabaseSetting/HighGo.md)
- [神通数据库配置指南](DatabaseSetting/Oscar.md)
- [GoldenDB 配置指南](DatabaseSetting/GoldenDB.md)
- [配置索引](DatabaseSetting/README.md)

---

## 🔄 从 1.x 迁移到 2.0

### ⚠️ 破坏性变更

DatabaseMcpServer 2.0.0 移除了环境变量配置方式，统一使用 JSON 配置文件。

### 迁移步骤

#### 1. 单数据库配置迁移

**旧方式（1.x - 已废弃）**:
```json
{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer",
      "env": {
        "DB_CONNECTION_STRING": "Server=localhost;Database=test;...",
        "DB_TYPE": "MySql",
        "DB_DM_LOWERCASE_TABLES": "true"
      }
    }
  }
}
```

**新方式（2.0）**:

1. 创建 `databases.json` 文件：
```json
{
  "databases": [
    {
      "name": "default",
      "connectionString": "Server=localhost;Database=test;...",
      "dbType": "MySql",
      "description": "默认数据库",
      "isDefault": true,
      "enableDangerousOperations": false,
      "optimizationSettings": {
        "lowercaseTables": "true"
      }
    }
  ]
}
```

2. 更新 MCP 配置：
```json
{
  "mcpServers": {
    "database": {
      "command": "DatabaseMcpServer",
      "env": {
        "DB_CONFIG_PATH": "D:\\config\\databases.json"
      }
    }
  }
}
```

#### 2. 环境变量映射表

| 旧环境变量 | 新 JSON 配置路径 |
|-----------|----------------|
| `DB_CONNECTION_STRING` | `databases[].connectionString` |
| `DB_TYPE` | `databases[].dbType` |
| `DB_DM_LOWERCASE_TABLES` | `databases[].optimizationSettings.lowercaseTables` |
| `DB_KDBNDP_MODE` | `databases[].optimizationSettings.mode` |
| `DB_GAUSSDB_NATIVE_DRIVER` | `databases[].optimizationSettings.nativeDriver` |
| `DB_ORACLE_CAMEL_CASE` | `databases[].optimizationSettings.camelCase` |
| `DB_POSTGRES_AUTO_TO_LOWER` | `databases[].optimizationSettings.autoToLower` |
| `DB_SQLITE_ENABLE_DEFAULT_VALUE` | `databases[].optimizationSettings.enableDefaultValue` |
| `DB_DISABLE_NVARCHAR` | `databases[].optimizationSettings.disableNvarchar` |

完整映射表请参考各数据库配置文档。

#### 3. 自动迁移检测

如果您仍在使用旧的环境变量配置，DatabaseMcpServer 2.0.0 会自动检测并显示详细的迁移提示。

### 常用数据库连接字符串示例

| 数据库 | 连接字符串示例 | 详细文档 |
|--------|---------------|---------|
| **MySQL** | `Server=localhost;Port=3306;Database=mydb;User=root;Password=123456;` | [MySQL.md](DatabaseSetting/MySQL.md) |
| **PostgreSQL** | `Host=localhost;Port=5432;Database=mydb;Username=postgres;Password=123456;` | [PostgreSQL.md](DatabaseSetting/PostgreSQL.md) |
| **SQL Server** | `Server=localhost;Database=mydb;User Id=sa;Password=123456;` | [SQLServer.md](DatabaseSetting/SQLServer.md) |
| **Oracle** | `Data Source=localhost/orcl;User ID=system;Password=oracle123;` | [Oracle.md](DatabaseSetting/Oracle.md) |
| **MongoDB** | `mongodb://localhost:27017/mydb` | [MongoDB.md](DatabaseSetting/MongoDB.md) |
| **SQLite** | `Data Source=mydb.db;` | [SQLite.md](DatabaseSetting/SQLite.md) |
| **ClickHouse** | `Host=localhost;Port=8123;User=default;Password=;Database=default;` | [ClickHouse.md](DatabaseSetting/ClickHouse.md) |
| **TiDB** | `Server=localhost;Port=4000;Database=mydb;User=root;Password=123456;` | [TiDB.md](DatabaseSetting/TiDB.md) |
| **OceanBase** | `Server=localhost;Port=2881;Database=mydb;User=root@sys;Password=123456;` | [OceanBase.md](DatabaseSetting/OceanBase.md) |
| **OceanBase (Oracle 模式)** | `Driver={OceanBase ODBC 2.0 Driver};Server=172.19.9.9;Port=2883;Database=TRD;User=USER@TENANT#CLUSTER:1650773680;Password=123456;Option=3;` | [OceanBase.md](DatabaseSetting/OceanBase.md) |
| **QuestDB** | `host=localhost;port=8812;username=admin;password=quest;database=qdb;ServerCompatibilityMode=NoTypeLoading;` | [QuestDb.md](DatabaseSetting/QuestDb.md) |
| **DuckDB** | `DataSource=train_services.db` | [DuckDB.md](DatabaseSetting/DuckDB.md) |
| **达梦数据库** | `Server=localhost;Port=5236;Database=mydb;User=SYSDBA;Password=SYSDBA001;` | [DM.md](DatabaseSetting/DM.md) |
| **人大金仓** | `Server=localhost;Port=54321;Database=mydb;User=SYSTEM;Password=system123;` | [Kdbndp.md](DatabaseSetting/Kdbndp.md) |
| **GBase 8s** | `Host=localhost;Service=19088;Server=gbase01;Database=testdb;Protocol=onsoctcp;Uid=gbasedbt;Pwd=GBase123;Db_locale=zh_CN.utf8;Client_locale=zh_CN.utf8` | [GBase.md](DatabaseSetting/GBase.md) |
| **GaussDB / OpenGauss** | `PORT=5432;DATABASE=mydb;HOST=localhost;PASSWORD=Gauss@123;USER ID=gaussdb;` | [GaussDB.md](DatabaseSetting/GaussDB.md) |
| **PolarDB** | `Server=localhost;Port=3306;Database=mydb;User=root;Password=123456;` | [PolarDB.md](DatabaseSetting/PolarDB.md) |
| **Vastbase** | `Host=localhost;Port=5432;Database=mydb;Username=vastbase;Password=123456;` | [Vastbase.md](DatabaseSetting/Vastbase.md) |
| **TDengine** | `Host=localhost;Port=6030;Username=root;Password=taosdata;Database=power` | [TDengine.md](DatabaseSetting/TDengine.md) |
| **瀚高数据库** | `Server=localhost;Port=5866;Database=mydb;Uid=highgo;Pwd=123456;` | [HighGo.md](DatabaseSetting/HighGo.md) |
| **神通数据库** | `Data Source=localhost;User Id=sysdba;Password=oracle;` | [Oscar.md](DatabaseSetting/Oscar.md) |
| **GoldenDB** | `Server=localhost;Port=1888;Database=mydb;Uid=golden;Pwd=123456;` | [GoldenDB.md](DatabaseSetting/GoldenDB.md) |

更多连接字符串和优化配置请参考 [DatabaseSetting/](DatabaseSetting/) 目录下的详细文档。

---

## 📋 完整功能清单（约 55 个工具）

逐工具参数、返回行为、CLI 示例和 `--yes` 要求见 [TOOLS.md](TOOLS.md)。

### 🔌 一、连接与配置管理

**基础连接管理**:
- **test_connection** - 测试当前数据库连接
- **test_connection_by_name** - 测试指定数据库的连接
- **get_database_config** - 获取当前数据库配置信息
- **validate_configuration** - 验证数据库配置是否正确
- **reload_database_config** - 重新加载 `databases.json` 并刷新当前配置缓存

**多数据库管理**:
- **list_databases** - 列出所有可用的数据库连接
- **switch_database** - 切换到指定的数据库
- **get_current_database** - 获取当前活动的数据库

**性能与健康检查**:
- **health_check** - 对所有数据库连接执行健康检查（响应时间、连接状态）
- **test_connection_with_retry** - 带自动重试的连接测试（指数退避策略）

### 🔍 二、数据库架构查询

- **get_data_base_list** - 获取所有数据库名称
- **get_table_info_list** - 获取所有表名
- **get_view_info_list** - 查询所有视图
- **get_column_infos_by_table_name** - 根据表名获取字段信息
- **get_table_schema** - 获取表的完整结构信息
- **get_is_identities** - 获取自增列
- **get_primaries** - 获取主键
- **get_index_list** - 获取所有索引名字集合
- **get_proc_list** - 获取存储过程名字集合
- **get_func_list** - 获取函数集合
- **get_trigger_names** - 根据表名获取触发器集合

### 🔎 三、存在性检查

- **is_any_table** - 判断表是否存在
- **is_any_column** - 判断列是否存在
- **is_any_constraint** - 判断约束是否存在
- **is_any_table_remark** - 判断是否存在表描述

### 📊 四、数据查询工具

**基础查询：**
- **sql_query** - 执行 SQL 查询并返回强类型实体集合（支持参数化查询，可选 `commandTimeoutSeconds`）
- **sql_query_single** - 执行 SQL 查询并返回单条记录（可选超时）

**高级查询：**
- **get_data_set_all** - 获取多个结果集，支持一次执行多个查询（可选超时）
- **sql_query_with_in_parameter** - 处理 IN 参数查询，支持数组参数（可选超时）
- **batch_sql_query** - 顺序执行 1-5 条只读 SQL，并逐条返回成功结果或错误（可选超时作用于批内每条）

**标量值查询：**
- **get_scalar** - 获取首行首列的值（标量值，可选超时）

### ✏️ 五、数据操作工具

- **execute_command** - 执行 SQL 命令（INSERT、UPDATE、DELETE；可选 `commandTimeoutSeconds`）
- **batch_execute_commands** - 批量执行 SQL 命令（性能优化；可选超时作用于批内每条）
- **call_stored_procedure** - 调用存储过程（简单用法；可选超时）
- **call_stored_procedure_with_output** - 调用带有输出参数的存储过程（可选超时）
- **execute_command_with_go** - 执行包含 GO 语句的 SQL Server 脚本（可选超时）

### 🛠️ 六、数据库架构操作（高风险）

**表操作：**
- **create_table** - 创建表（使用列定义 JSON 数组）
- **drop_table** - 删除表
- **truncate_table** - 清空表
- **backup_table** - 备份表
- **rename_table** - 重命名表

**列操作：**
- **add_column** - 添加列
- **update_column** - 更新列
- **drop_column** - 删除列
- **rename_column** - 重命名列

**约束和索引：**
- **add_primary_key** - 添加主键
- **drop_constraint** - 删除约束
- **create_index** - 创建索引或唯一约束

**其他：**
- **add_default_value** - 添加默认值
- **add_table_remark** - 添加表描述
- **add_column_remark** - 添加列描述
- **delete_table_remark** - 删除表描述
- **delete_column_remark** - 删除列描述

*完整工具列表请参考 [.mcp/server.json](.mcp/server.json)*

## 💡 使用示例

### 示例 1：基础连接与查询

**测试数据库连接**
```
测试数据库连接
```

**列出所有表**
```
列出当前数据库的所有表
```

**查询用户数据**
```
查询 users 表中的所有数据
```

### 示例 2：参数化查询

**条件查询**
```
查询 users 表中年龄大于 25 岁的活跃用户，按创建时间倒序排列
```

**IN 参数查询**
```
查询用户ID在 [1,2,3,4,5] 中的用户信息
```

**多条件查询**
```
查询城市为"北京"、年龄在 20-30 之间、状态为活跃的用户
```

### 示例 3：数据统计与分析

**聚合查询**
```
统计 products 表中每个分类的商品数量和平均价格
```

**多结果集查询**
```
同时查询：1) 用户总数和活跃用户数量 2) 最近 7 天的订单数据
```

**标量值查询**
```
获取订单表中订单状态为"已完成"的总金额
```

### 示例 4：数据操作

**插入新数据**
```
向 products 表插入新商品：名称为"MacBook Pro M3"，价格为 14999，库存为 50
```

**批量更新**
```
批量更新以下用户的VIP状态：用户ID 1,3,5,7,9 设置为VIP，其他设置为普通用户
```

**事务操作**
```
执行转账操作：从账户A(ID:1001)转账 500 元到账户B(ID:1002)
```

### 示例 5：架构查询

**获取表结构**
```
获取 orders 表的完整结构信息：列、主键、索引、自增列等
```

**查询索引信息**
```
查询 users 表的所有索引信息
```

**检查表是否存在**
```
检查数据库中是否存在名为"user_logs"的表
```

### 示例 6：存储过程调用

**简单存储过程**
```
调用存储过程 sp_monthly_report，传入参数年份 2025，月份 11
```

**带输出参数的存储过程**
```
调用存储过程 sp_user_statistics，传入用户ID 1001，获取该用户的订单总数和总金额
```

## 🔒 安全特性

### 危险操作检测
系统自动检测并阻止以下危险操作：
- `DROP TABLE` / `DROP DATABASE` - 删除表/数据库
- `TRUNCATE TABLE` - 清空表数据
- `ALTER TABLE` - 修改表结构
- 无 WHERE 条件的 `DELETE` / `UPDATE`

如需执行这些操作，建议优先使用专门的架构操作工具（如 `create_table`、`drop_table`、`truncate_table` 等），这些工具会明确提示风险。若确需通过 `execute_command`、`execute_command_with_go` 或 `batch_execute_commands` 执行 DDL，可在当前连接配置中显式设置 `"enableDangerousOperations": true`，或使用 `config update --enable-dangerous-operations true` 写入配置；默认值为 `false`。

兼容旧配置字段 `allowDangerousOperations` 和 CLI 参数 `--allow-dangerous-operations`。配置保存时统一写入 `enableDangerousOperations`；新旧 JSON 字段同时存在时，以新字段为准，与字段顺序无关。

### SQL 注入防护
所有查询都支持参数化查询，自动防止 SQL 注入：

```json
{
  "sql": "SELECT * FROM users WHERE age > @age AND city = @city",
  "parameters": "{\"age\":18,\"city\":\"北京\"}"
}
```

### SQL 命令超时
查询与数据操作类工具支持可选参数 `commandTimeoutSeconds`（CLI：`--command-timeout-seconds`）：

- 省略：使用 SqlSugar/驱动默认（通常 300 秒）
- `0`：无限等待
- 合法范围：`0–86400`
- 批处理工具上的超时作用于整批

```json
{
  "sql": "SELECT * FROM large_report WHERE day = @day",
  "parameters": "{\"day\":\"2026-08-01\"}",
  "commandTimeoutSeconds": 900
}
```

```bash
DatabaseMcpServer tool execute_command \
  --sql 'update large_table set status=@status where id=@id' \
  --parameters '{"status":"done","id":1}' \
  --command-timeout-seconds 900 \
  --yes
```

完整参数说明见 [TOOLS.md](TOOLS.md)。

### 敏感信息保护
- 连接字符串中的密码自动隐藏（显示为 `Password=****`）
- 日志中不输出完整连接字符串
- 配置信息返回时自动脱敏

## 💻 开发指南

### 本地开发

```bash
# 克隆项目
git clone https://github.com/ttcc666/DatabaseMcpServer.git
cd DatabaseMcpServer

# 创建配置文件 databases.json 后运行
DB_CONFIG_PATH="path/to/databases.json" dotnet run --framework net9.0

# 或使用 .NET 10
DB_CONFIG_PATH="path/to/databases.json" dotnet run --framework net10.0

# 构建项目
dotnet build 'DatabaseMcpServer.slnx'

# 运行测试
dotnet test 'tests\DatabaseMcpServer.Tests\DatabaseMcpServer.Tests.csproj'

# 打包发布
dotnet pack 'src\DatabaseMcpServer\DatabaseMcpServer.csproj' -c Release
```

推荐的稳定验证方式：

```powershell
.\scripts\verify.ps1
```

## 🆕 版本发布

- **3.7.0**
  - 新增可选配置文件监听，长驻 MCP stdio / `-web` 可在默认库变化时自动切换当前连接；优先级为启动参数 `--enable-monitor-config` > 环境变量 `ENABLE_MONITOR_CONFIG` > 配置字段 `enableMonitorConfig`，默认关闭
  - MCP stdio 未设置 `DB_CONFIG_PATH` 时，自动读取用户目录下的 `.database-mcp/databases.json`
  - 危险操作配置统一使用 `enableDangerousOperations`，兼容旧字段及 `--allow-dangerous-operations` 参数；新旧 JSON 字段同时存在时以新字段为准
  - 修复 Web 修改默认库后的运行时切换，并将配置路径测试隔离到临时用户目录

- **3.6.6**
  - 查询与数据操作类工具新增可选 `commandTimeoutSeconds`（CLI：`--command-timeout-seconds`），可覆盖默认约 300 秒超时
  - 指定超时通过 `CopyNew()` 隔离客户端，避免污染共享连接池；`0` 表示无限等待，合法范围 `0–86400`
  - 同步 `TOOLS.md`、CLI/skill 文档与单测覆盖

- **3.6.5**
  - 升级 `ModelContextProtocol` 到 2.0.0，并按新版本配置 `ServerInfo` 与工具 `ReadOnly`/`Destructive`/`Idempotent` 注解
  - 同步升级 `Microsoft.Extensions.*`、`SqlSugarCore`、`Serilog.Sinks.Seq` 与测试 SDK 到最新稳定版
  - 构建与 94 项单元测试通过（net9.0 / net10.0）

- **3.6.0**
  - 本地 Web 控制台新增中英文切换、界面文案国际化与语言偏好持久化
  - 使用应用级滚动容器并关闭弹层 body scroll lock，修复打开侧栏和下拉菜单时的界面抖动
  - 补充语言初始化与连接健康检查测试，并更新内嵌 production assets

- **3.5.5**
  - 修复 Oracle 连接检测执行 `SELECT 1` 时误报 `ORA-00923` 的问题
  - MCP 连接测试、健康检查、重试检测和 CLI doctor 统一使用方言无关连接探针
  - 补全 `create_table` 的 CLI 发布验证，覆盖全部 56 个 tools

- **3.5.0**
  - 新增 `create_table` 工具，支持通过列定义 JSON 创建数据表
  - 新增连接级 `enableDangerousOperations` 配置，默认关闭危险 SQL
  - 阻止无 `WHERE` 的 `UPDATE` / `DELETE`，并将执行客户端与安全策略绑定为同一配置快照

- **3.0.0**
  - **Breaking**：移除 Excel 导出和数据库文档生成 tools，同时移除 `ClosedXML` 依赖
  - 新增 `batch_sql_query`，支持一次顺序执行 1-5 条只读查询并逐项返回结果
  - 明确 `batch_execute_commands` 为非事务批处理，单项失败不会回滚此前成功的命令
  - 统一源码/测试目录到 `src/` 与 `tests/`，修复 pooled `SqlSugarScope` 生命周期，并同步更新 CLI 文档与 skill

- **2.5.0**
  - 新增 `-web` 本地配置管理页，支持浏览器内维护 `databases.json` 与 `cli-state.json`
  - 前端重构为 `Vue 3 + shadcn-vue` 风格工作台，并补齐连接表格、编辑抽屉、诊断与导入导出交互
  - 修复 Web API fallback、非法 `--port` 崩溃和前端产物过期打包问题，补充对应测试覆盖

- **2.1.1**
  - 新增 `reload_database_config`，支持运行时重新加载 `DB_CONFIG_PATH` 指向的数据库配置
  - 刷新配置时同步清空客户端缓存，确保后续请求使用新的连接信息
  - 增补配置刷新与客户端重建测试，发版前验证覆盖更完整

- **2.2.2**
  - 修复 CLI 模式下 `switch_database` 仅在单次进程内生效的问题，改为按配置文件路径持久化“当前连接”
  - 新增状态恢复 / 配置路径隔离 / 失效连接回退默认连接的测试覆盖
  - 更新 NuGet / MCP manifest / README 版本元数据，便于 `2.2.2` 打包发布

- **2.2.1**
  - 收敛并优化 `database-mcp-cli` skill 的触发词、CLI 工作流说明与故障排查矩阵
  - 新增 `agents/openai.yaml`，补齐 UI metadata，使 skill 展示与触发语义一致
  - 更新 NuGet / MCP manifest / README 版本元数据，便于 `2.2.1` 打包发布

- **2.2.0**
  - 新增 CLI 模式：支持 `DatabaseMcpServer tool <tool_name>` 直接调用已有数据库工具
  - 保留无参数 stdio MCP server 兼容行为，并新增 `tool list` / `tool help` / `--config` / `--yes`
  - CLI 模式默认仅输出工具结果 JSON，避免日志污染 `stdout`
  - 补充 CLI 文档、全量 SQLite/SQL Server 验证脚本与 `database-mcp-cli` skill 草案

- **2.1.0**
  - 版本号统一至 2.1.0（徽标/示例命令/配置）
  - 为工具、服务、策略等补充中文 XML 注释，便于智能提示与维护
  - 精简冗余工具接口（多型标量/重复查询/重复 DML 包装），保持核心能力
  - 修复模型非空属性警告，构建无警告

### 添加新工具

1. **创建工具类文件**
   ```bash
   # 在 src/DatabaseMcpServer/Tools/ 目录下创建新工具类
   # Management/ - 连接和架构管理
   # Query/ - 查询工具
   # Command/ - 命令工具
   ```

2. **实现工具类**
   ```csharp
   using System.ComponentModel;
   using ModelContextProtocol.Server;
   using DatabaseMcpServer.Interfaces;

   namespace DatabaseMcpServer.Tools;

   [McpServerToolType]
   internal class YourNewTools
   {
       private readonly IDatabaseConfigService _databaseConfig;
       private readonly IDatabaseHelperService _databaseHelper;

       public YourNewTools(IDatabaseConfigService databaseConfig, IDatabaseHelperService databaseHelper)
       {
           _databaseConfig = databaseConfig;
           _databaseHelper = databaseHelper;
       }

       [McpServerTool]
       [Description("你的工具描述")]
       public string YourMethod([Description("参数描述")] string parameter)
       {
           var db = _databaseConfig.CreateClient();
           // 实现你的功能
           return _databaseHelper.SerializeResult(new { success = true, data = "result" });
       }
   }
   ```

3. **注册工具**
   在 `Program.cs` 中：
   ```csharp
   builder.Services
       .AddMcpServer()
       .WithStdioServerTransport()
       .WithTools<ConnectionTools>()
       .WithTools<SchemaTools>()
       .WithTools<QueryTools>()
       .WithTools<CommandTools>();
   ```

### 项目架构

```
MCP Protocol Layer (stdio)
    ↓
Tools Layer (Connection/Query/Command/Schema)
    ↓
Services Layer (DatabaseConfigService)
    ↓
Data Access Layer (SqlSugar ORM)
```

**关键组件：**
- `DatabaseConfigService` - 配置管理和连接创建
- `DatabaseHelper` - 数据库类型解析和安全检查
- `McpExceptionFilter` - 统一异常处理
- `ApiResult<T>` - 标准化返回格式

## 🛠️ 技术栈

- **.NET 9.0** - 最新的 .NET 平台
- **ModelContextProtocol 1.0.0** - MCP 协议 C# SDK
- **SqlSugarCore 5.1.4** - 轻量级高性能 ORM
- **Serilog** - 结构化日志框架
- **Microsoft.Extensions.Hosting** - 依赖注入和托管

## 📚 相关资源

- [MCP 官方文档](https://modelcontextprotocol.io/)
- [MCP GitHub](https://github.com/modelcontextprotocol)
- [SqlSugar 文档](https://github.com/DotNetNext/SqlSugar)
- [VS Code MCP 指南](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
- [NuGet Trusted Publishing 使用手册](Doc/trusted-publishing.md)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

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

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## ⚠️ 免责声明

- 本项目当前版本为 3.6.5
- 3.0.0 移除了 Excel 导出与数据库文档生成 tools，升级前请检查现有调用
- 2.0.0 版本包含破坏性变更，请参考迁移指南
- 生产环境使用前请充分测试
- 定期备份重要数据
- 注意配置中的敏感信息保护

---

**DatabaseMCP** - 让 AI 助手轻松操作数据库！