内容
# MCP SQL Server
MCP（模型上下文协议）用于管理 SQL Server 数据库。通过 FastMCP 暴露查询、分析、修改和连接配置工具。
---
## 需求
- Python 3.10+
- SQL Server 的 ODBC 驱动程序
- opencode（或任何 MCP 客户端）
### ODBC 驱动程序
**Windows**
```
下载并安装：https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server
```
**Linux (Ubuntu/Debian)**
```bash
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc
sudo add-apt-repository "$(curl -fsSL https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list)"
sudo apt-get update
sudo apt-get install -y mssql-tools18 unixodbc-dev
```
**Linux (RHEL/Fedora)**
```bash
sudo curl -o /etc/yum.repos.d/mssql-release.repo https://packages.microsoft.com/config/rhel/8/prod.repo
sudo yum install -y mssql-tools18 unixodbc-devel
```
---
## 安装
**1. 克隆仓库**
```bash
git clone <repo-url>
cd MCP_SQLSERVER
```
**2. 创建虚拟环境**
```bash
# Windows
python -m venv .venv
.venv\Scripts\activate
# Linux
python3 -m venv .venv
source .venv/bin/activate
```
**3. 安装依赖**
```bash
pip install -r requirements.txt
```
---
## 在 opencode 中配置 MCP
将以下内容添加到您的 opencode 配置文件（`opencode.json` 或 `~/.config/opencode/opencode.json`）中：
**Linux**
```json
{
"mcp": {
"sqlserver": {
"type": "local",
"enabled": true,
"command": [
"/full/path/to/MCP_SQLSERVER/.venv/bin/python",
"/full/path/to/MCP_SQLSERVER/Server.py"
]
}
}
}
```
**Windows**
```json
{
"mcp": {
"sqlserver": {
"type": "local",
"enabled": true,
"command": [
"C:\\full\\path\\to\\MCP_SQLSERVER\\.venv\\Scripts\\python.exe",
"C:\\full\\path\\to\\MCP_SQLSERVER\\Server.py"
]
}
}
}
```
---
## 入门（配置连接）
MCP 首次启动时，连接为空。助手将引导您使用以下工具配置连接：
| 工具 | 参数 | 描述 |
|---|---|---|
| `configure_connection` | server, auth_type, database, port, driver, username, password, trust_server_certificate, sql_repository | 一次设置所有参数 |
| `set_config` | server, port, database, driver, auth_type, username, password, trust_server_certificate, sql_repository | 仅更新给定字段（其他字段保持不变） |
| `get_config` | — | 显示当前配置（隐藏密码） |
| `test_connection` | database（可选） | 使用当前设置测试连接性 |
**典型流程：**
```
1. configure_connection(
server="MY-SERVER",
port="1433",
auth_type="sqlserver",
username="my_user",
password="my_password",
database="MyDB"
)
2. test_connection()
3. list_databases()
4. list_tables("MyDB")
5. describe_table("MyDB", "MyTable")
```
### 身份验证类型
- **windows**：使用 `Trusted_Connection=yes`。不需要用户名或密码（域会话）。
- **sqlserver**：使用 `UID` 和 `PWD`。需要用户名和密码。
> 配置保存在 `config.json` 中。您可以在任何时候通过再次调用 `configure_connection` 或 `set_config` 更改服务器或数据库。
---
## MCP 工具
### 配置
| 工具 | 参数 | 描述 |
|---|---|---|
| `get_config` | — | 显示当前配置（隐藏密码） |
| `set_config` | server, port, database, driver, auth_type, username, password, trust_server_certificate, sql_repository | 更新 `config.json` 中的特定字段 |
| `configure_connection` | server, auth_type, database, port, driver, username, password, trust_server_certificate, sql_repository | 一次设置所有连接参数 |
| `test_connection` | database（可选） | 使用当前配置测试连接性 |
### 对象探索
| 工具 | 参数 | 描述 |
|---|---|---|
| `ping` | — | 检查 SQL Server 连接性 |
| `list_databases` | — | 列出所有活动数据库 |
| `list_tables` | database | 列出数据库中的表 |
| `describe_table` | database, table | 列、类型、空值、默认值 |
| `list_procedures` | database | 列出存储过程 |
| `describe_procedure` | database, procedure | 存储过程的源代码和参数 |
| `list_functions` | database | 列出函数 |
| `describe_function` | database, function | 函数的源代码和参数 |
| `search_tables` | database, text | 按部分名称搜索表（LIKE） |
| `search_columns` | database, text | 按名称搜索列 |
| `search_procedures` | database, text | 按部分名称搜索存储过程 |
| `search_text` | database, text | 在存储过程/函数定义中搜索文本 |
| `list_foreign_keys` | database | 列出数据库中的所有外键 |
| `find_relationships` | database, table | 表的传入和传出关系 |
### 数据操作
| 工具 | 参数 | 描述 |
|---|---|---|
| `execute_query` | database, query | SELECT 或 CTE（只读且验证） |
| `execute_dml` | database, query, confirmed | INSERT/UPDATE/DELETE（需要 confirmed=True） |
| `execute_ddl` | database, sql_text, description | CREATE/ALTER 且自动迁移 |
---
## 变更跟踪（日志和迁移）
每次运行 `execute_ddl`（CREATE/ALTER）时，系统会自动在 `sql_repository` 中保存完整的历史记录。您永远不会丢失已修改的内容。
### 保存了什么？
```
sql_repository/
└── MyDB/
├── Procedures/
│ └── MyProcedure/
│ └── Current.sql ← 当前定义及历史记录
├── Functions/
├── Views/
├── Tables/
├── Migrations/
│ └── Procedures/
│ └── 20260724_001_MyProcedure.sql ← 每次更改都是一个文件
└── Logs/
└── Changes.jsonl ← JSONL 格式的全审计日志
```
- **Current.sql**：包含当前对象定义以及带有历史记录的 `HISTORY` 块，包括每次更改的日期、作者和摘要。
- **Migrations/**：每个 DDL 生成一个版本 SQL 文件（`YYYYMMDD_NNN_Name.sql`），包含确切的更改。您可以手动审查或回滚。
- **Logs/Changes.jsonl**：JSONL 格式的审计日志（一行一个更改），易于使用脚本处理或 grep 搜索。
### Changes.jsonl 中的示例条目
```json
{"date": "2026-07-24T20:04:33", "database": "MyDB", "objectType": "PROCEDURE", "object": "MyProcedure", "operation": "CREATE", "description": "Create test procedure", "migration": "20260724_001_MyProcedure.sql"}
```
### 为什么重要？
- 您可以随时恢复到任何对象的先前版本。
- 您确切地知道更改了什么、何时更改以及谁更改的。
- 完整的 `sql_repository` 可以在 Git 中版本控制，以实现端到端的可追溯性。
