npm package: @liangshanli/mcp-server-mssqlserver
Description: MCP MSSQL Server with DDL support, permission control and operation logs
Author: liliangshan
Latest version: 2.0.1

# MSSQL Server MCP 服务器

一个功能强大的基于 Model Context Protocol (MCP) 的 MSSQL Server 服务器，提供企业级 DDL 支持、细粒度权限控制、全面的操作日志记录和智能连接池管理。

## 🚀 核心功能特性

### 主要能力
- **完整 SQL 支持**: 支持 DDL 和 DML 操作，具备 SQL 注入防护
- **高级权限控制**: 通过环境变量对 DDL、DROP、DELETE 操作进行细粒度控制
- **全面日志记录**: 完整的请求响应日志、SQL 操作跟踪和连接池监控
- **企业级连接管理**: 自动连接池创建、健康监控和故障恢复
- **MCP 协议兼容**: 完整的 Model Context Protocol 实现，支持工具发现和执行
- **多编辑器支持**: 与 Cursor、VS Code 等 MCP 兼容编辑器无缝集成

### 高级特性
- **架构自动前缀**: 多租户环境的自动架构处理
- **连接池优化**: 智能连接复用和性能调优
- **错误处理**: 全面的错误日志记录和优雅的故障恢复
- **安全特性**: SQL 注入防护、参数化查询支持和操作验证

## 📦 安装

### NPM 安装

#### 全局安装（推荐）
```bash
npm install -g @liangshanli/mcp-server-mssqlserver
```

#### 本地安装
```bash
npm install @liangshanli/mcp-server-mssqlserver
```

### 手动安装
```bash
git clone https://github.com/liliangshan/mcp-server-mssqlserver.git
cd mcp-server-mssqlserver
npm install
```

## ⚙️ 配置

### 环境变量

#### 数据库连接设置
| 环境变量 | 默认值 | 描述 | 必需 |
|---------|--------|------|------|
| `MSSQL_SERVER` | `localhost` | MSSQL Server 主机地址 | ✅ |
| `MSSQL_PORT` | `1433` | MSSQL Server 端口号 | ✅ |
| `MSSQL_USER` | `sa` | 数据库用户名 | ✅ |
| `MSSQL_PASSWORD` | `` | 数据库密码 | ✅ |
| `MSSQL_DATABASE` | `` | 目标数据库名称 | ✅ |
| `MSSQL_SCHEMA` | `dbo` | 默认架构名称 | ✅ |
| `MSSQL_ENCRYPT` | `false` | 启用加密 | ❌ |
| `MSSQL_TRUST_SERVER_CERTIFICATE` | `true` | 信任服务器证书 | ❌ |

#### 权限控制设置
| 环境变量 | 默认值 | 描述 | 安全级别 |
|---------|--------|------|----------|
| `ALLOW_DDL` | `false` | 允许 CREATE、ALTER、DROP 操作 | 🔴 高风险 |
| `ALLOW_DROP` | `false` | 允许 DROP TABLE 操作 | 🔴 高风险 |
| `ALLOW_DELETE` | `false` | 允许 DELETE 操作 | 🟡 中风险 |

#### 日志配置
| 环境变量 | 默认值 | 描述 |
|---------|--------|------|
| `MCP_LOG_DIR` | `./logs` | 日志目录路径 |
| `MCP_LOG_FILE` | `mcp-mssqlserver.log` | 日志文件名 |

### 安全配置示例

#### 开发环境（高权限）
```bash
export ALLOW_DDL=true
export ALLOW_DROP=true
export ALLOW_DELETE=true
```

#### 测试环境（中等权限）
```bash
export ALLOW_DDL=true
export ALLOW_DROP=false
export ALLOW_DELETE=true
```

#### 生产环境（限制权限）
```bash
export ALLOW_DDL=false
export ALLOW_DROP=false
export ALLOW_DELETE=false
```

## 🚀 使用方法

### 启动服务器

#### 方式 1: CLI 启动
```bash
npm start
```

#### 方式 2: 直接运行服务器
```bash
npm run server
```

#### 方式 3: 托管模式启动
```bash
npm run start-managed
```

#### 方式 4: 开发模式启动（带调试）
```bash
npm run dev
```

### 完整环境设置示例

```bash
# 数据库连接
export MSSQL_SERVER=your-mssql-server.com
export MSSQL_PORT=1433
export MSSQL_USER=your-username
export MSSQL_PASSWORD=your-secure-password
export MSSQL_DATABASE=your-database
export MSSQL_SCHEMA=your-schema

# 安全权限
export ALLOW_DDL=true
export ALLOW_DROP=false
export ALLOW_DELETE=true

# 日志配置
export MCP_LOG_DIR=/var/log/mcp
export MCP_LOG_FILE=mssqlserver.log

# 启动服务器
npm start
```

## 🛠️ 可用工具

### 1. sql_query
执行 SQL 查询，支持完整的 DDL 和 DML 操作。

**参数:**
- `sql` (string, 必需): 要执行的 SQL 语句

**特性:**
- 自动架构前缀处理
- 权限验证
- 全面错误处理
- SQL 注入防护

**示例:**
```json
{
  "name": "sql_query",
  "arguments": {
    "sql": "SELECT * FROM users WHERE id = 1"
  }
}
```

**支持的操作:**
- ✅ SELECT 查询
- ✅ INSERT 操作
- ✅ UPDATE 操作
- ✅ DELETE 操作（如果允许）
- ✅ CREATE TABLE（如果 DDL 允许）
- ✅ ALTER TABLE（如果 DDL 允许）
- ✅ DROP TABLE（如果 DROP 允许）

### 2. get_database_info
获取全面的数据库信息和配置详情。

**参数:** 无

**返回信息:**
- 数据库列表
- 当前数据库的表列表
- 当前配置
- 权限状态
- 连接信息

**示例:**
```json
{
  "name": "get_database_info",
  "arguments": {}
}
```

### 3. get_operation_logs
访问详细的操作日志，用于监控和调试。

**参数:**
- `limit` (number, 可选): 返回的日志条目数量（默认: 50）
- `offset` (number, 可选): 分页起始位置（默认: 0）

**日志信息:**
- 请求/响应详情
- SQL 执行结果
- 错误消息和堆栈跟踪
- 连接池状态
- 性能指标

**示例:**
```json
{
  "name": "get_operation_logs",
  "arguments": {
    "limit": 100,
    "offset": 0
  }
}
```

### 4. check_permissions
验证当前权限配置和访问权限。

**参数:** 无

**返回信息:**
- 当前权限设置
- 环境变量状态
- 配置验证
- 安全建议

**示例:**
```json
{
  "name": "check_permissions",
  "arguments": {}
}
```

## 📊 日志记录和监控

### 日志分类

#### 1. 请求/响应日志
- 所有 MCP 方法调用
- 参数验证
- 响应生成
- 错误处理

#### 2. SQL 操作日志
- SQL 语句执行
- 查询结果
- 性能指标
- 错误详情

#### 3. 连接池日志
- 池创建/销毁
- 健康检查结果
- 连接失败
- 恢复尝试

#### 4. 系统事件日志
- 服务器启动/关闭
- 配置更改
- 权限更新
- 安全事件

### 日志文件位置
- **默认**: `./logs/mcp-mssqlserver.log`
- **可自定义**: 通过 `MCP_LOG_DIR` 和 `MCP_LOG_FILE` 环境变量

### 日志格式
```
2025-01-15T10:30:00.000Z | method_name | {"param1": "value1"} | SUCCESS | RESPONSE: {"result": "data"}
2025-01-15T10:30:01.000Z | SQL: SELECT * FROM users | SUCCESS
```

## 🔒 安全特性

### 权限控制
- **细粒度访问控制**: 对不同操作类型的精细权限管理
- **基于环境的安全**: 通过环境变量进行安全配置
- **操作验证**: SQL 执行前实时权限检查
- **审计日志**: 所有操作的完整审计跟踪

### SQL 注入防护
- **参数化查询**: 支持预处理语句
- **输入验证**: 全面的输入清理
- **错误屏蔽**: 安全的错误消息处理
- **查询日志**: 完整的 SQL 操作跟踪

### 连接安全
- **加密连接**: 支持 SSL/TLS 加密
- **证书验证**: 可配置的证书信任设置
- **连接池**: 安全的连接管理
- **超时保护**: 可配置的连接和请求超时

## 🎯 编辑器集成

### Cursor 编辑器配置

1. 在项目根目录创建 `.cursor/mcp.json` 文件：

```json
{
  "mcpServers": {
    "mssqlserver": {
      "command": "npx",
      "args": ["@liangshanli/mcp-server-mssqlserver"],
      "env": {
        "MSSQL_SERVER": "your_host",
        "MSSQL_PORT": "1433",
        "MSSQL_USER": "your_user",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "your_database",
        "MSSQL_SCHEMA": "your_schema",
        "MSSQL_ENCRYPT": "false",
        "MSSQL_TRUST_SERVER_CERTIFICATE": "true",
        "ALLOW_DDL": "false",
        "ALLOW_DROP": "false",
        "ALLOW_DELETE": "false"
      }
    }
  }
}
```

### VS Code 配置

1. 安装 VS Code 的 MCP 扩展
2. 创建 `.vscode/settings.json` 文件：

```json
{
  "mcp.servers": {
    "mssqlserver": {
      "command": "npx",
      "args": ["@liangshanli/mcp-server-mssqlserver"],
      "env": {
        "MSSQL_SERVER": "your_host",
        "MSSQL_PORT": "1433",
        "MSSQL_USER": "your_user",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DATABASE": "your_database",
        "MSSQL_SCHEMA": "your_schema",
        "MSSQL_ENCRYPT": "false",
        "MSSQL_TRUST_SERVER_CERTIFICATE": "true",
        "ALLOW_DDL": "false",
        "ALLOW_DROP": "false",
        "ALLOW_DELETE": "false"
      }
    }
  }
}
```

### 直接使用 MCP 服务器

服务器通过 stdin/stdout 与 MCP 客户端通信：

```json
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}}
```

## 🔧 连接池管理

### 自动特性
- **自动创建**: 在 `notifications/initialized` 时自动创建连接池
- **健康监控**: 5分钟间隔的健康检查
- **自动恢复**: 失败时自动重新创建池
- **性能优化**: 智能连接复用
- **优雅关闭**: 服务器终止时正确清理连接

### 配置选项
- **池大小**: 可配置的最小和最大连接数
- **超时设置**: 可自定义的连接和请求超时
- **重试逻辑**: 失败连接的可配置重试尝试
- **负载均衡**: 智能连接分发

## 🚨 故障排除

### 常见问题

#### 1. 连接失败
**症状:**
- "Connection refused" 错误
- 超时错误
- 认证失败

**解决方案:**
- 验证 MSSQL Server 是否运行
- 检查防火墙设置
- 验证连接参数
- 确认网络连接性

#### 2. 权限错误
**症状:**
- "Operation not allowed" 错误
- "Access denied" 消息
- 权限验证失败

**解决方案:**
- 检查环境变量配置
- 验证数据库用户权限
- 确认 ALLOW_* 设置
- 审查安全配置

#### 3. 日志问题
**症状:**
- 缺少日志文件
- 不完整的日志条目
- 权限被拒绝错误

**解决方案:**
- 检查日志目录权限
- 验证磁盘空间可用性
- 确认日志文件路径有效性
- 审查文件系统权限

### 调试模式

启用详细的调试信息：

```bash
npm run dev
```

**调试信息:**
- 详细的 SQL 执行日志
- 连接池状态
- 权限验证详情
- 错误堆栈跟踪
- 性能指标

## 🏗️ 开发

### 项目结构
```
mcp-server-mssqlserver/
├── bin/
│   └── cli.js              # CLI 启动脚本
├── src/
│   └── server-final.js     # 主要服务器实现
├── start-server.js         # 托管启动脚本
├── package.json            # 项目配置
├── README.md              # 英文文档
├── README.zh-CN.md        # 中文文档
└── SCHEMA_USAGE.md        # 架构使用指南
```

### 构建和测试

```bash
# 安装依赖
npm install

# 运行基本测试
npm test

# 运行全面测试
npm run test-full

# 启动开发服务器
npm run dev

# 生产环境构建
npm run build
```

### 开发特性
- **热重载**: 代码更改时自动服务器重启
- **调试日志**: 全面的调试信息
- **错误处理**: 详细的错误报告和堆栈跟踪
- **性能监控**: 实时性能指标

## 📄 许可证

MIT License - 详情请参阅 LICENSE 文件

## 🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南：

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

### 贡献领域
- **错误修复**: 报告和修复错误
- **功能开发**: 添加新功能
- **文档**: 改进文档
- **测试**: 添加测试覆盖
- **性能**: 优化性能

## 🔗 相关链接

- [Model Context Protocol](https://modelcontextprotocol.io/) - 官方 MCP 规范
- [MSSQL Node.js Driver](https://github.com/tediousjs/node-mssql) - 数据库驱动文档
- [MCP Specification](https://spec.modelcontextprotocol.io/) - 完整协议文档
- [GitHub Repository](https://github.com/liliangshan/mcp-server-mssqlserver) - 源代码和问题

## 📞 支持

### 获取帮助
- **GitHub Issues**: 报告错误和请求功能
- **文档**: 全面的指南和示例
- **示例**: 工作示例和用例
- **社区**: 加入我们的开发者社区

### 版本兼容性
- **Node.js**: 18.x 或更高版本
- **MSSQL Server**: 2012 或更高版本
- **MCP Protocol**: 2025-06-18 或兼容版本

## 💡 使用场景

### 1. 开发环境
- 为开发人员提供安全的数据库访问接口
- 支持完整的 DDL 操作进行表结构设计
- 详细的日志记录帮助调试和问题排查

### 2. 测试环境
- 支持自动化测试和数据库操作验证
- 限制危险操作权限保护测试数据
- 完整的操作审计跟踪

### 3. 生产环境
- 通过严格的权限控制保护生产数据库
- 企业级连接池管理确保高可用性
- 全面的安全防护和监控

### 4. AI 助手集成
- 为 AI 工具提供安全的数据库操作能力
- 支持自然语言到 SQL 的转换
- 智能权限管理和操作验证

## 🔐 安全最佳实践

### 权限配置建议
- **开发阶段**: 启用所有权限进行功能测试
- **测试阶段**: 限制 DROP 操作，允许 DDL 和 DELETE
- **预生产**: 严格限制所有危险操作权限
- **生产环境**: 仅允许必要的查询操作

### 网络安全
- 使用防火墙限制数据库访问
- 启用 SSL/TLS 加密连接
- 定期更新数据库用户密码
- 监控异常访问模式

### 审计和监控
- 启用完整的操作日志记录
- 定期审查权限配置
- 监控数据库性能指标
- 设置告警机制