Metadata-Version: 2.4
Name: mssql-mcp-vn
Version: 0.2.1
Summary: MSSQL MCP server with read-only queries, backups, and schema comparison
Author-email: NamHT <namht.dev@gmail.com>
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.27.0
Requires-Dist: pymssql>=2.3.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: pydantic-settings>=2.4.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"

# MSSQL MCP Server

MCP server Python cho Microsoft SQL Server, dùng `pymssql`/FreeTDS nên không cần ODBC
driver. Bản `0.2.0` hỗ trợ truy vấn chỉ đọc, full backup `.bak` chạy nền và so sánh
relational schema giữa hai database trên cùng instance.

## Tools

- `mssql_list_databases()`: liệt kê database `ONLINE` mà principal nhìn thấy.
- `mssql_execute_query(database_name, query, limit=100)`: chỉ nhận `SELECT` hoặc CTE
  chỉ đọc; chặn `EXEC`, `SELECT INTO`, DDL/DML, `BACKUP`, `RESTORE` và `DBCC`.
- `mssql_list_tables(database_name, schema_name="dbo")`.
- `mssql_describe_table(database_name, table_name, schema_name="dbo")`.
- `mssql_start_backup(database_name)`: full `COPY_ONLY`, `CHECKSUM`, tự động bỏ
  `COMPRESSION` trên SQL Server Express, một job tại một thời điểm. Tool trả ngay
  `backup_id` sau preflight.
- `mssql_get_backup_status(backup_id)`: trả `queued | running | succeeded | failed`,
  `percent_complete`, paths, kích thước file, verify và lỗi có hướng xử lý.
- `mssql_compare_schemas(source_database, target_database, schema_name=null,
  offset=0, limit=100)`: so sánh tables, columns, PK, FK, unique/check constraints và
  indexes; `limit` từ 1 đến 500.

Mọi argument public đều truyền phẳng, không bọc trong `params`.

## Cài và chạy

```bash
cd uvx/mssql
uv sync --extra dev
uv run mssql-mcp-vn
```

Stdio là mặc định. Streamable HTTP dùng tên SDK `streamable-http`; alias
`streamable_http` vẫn được chấp nhận và bind loopback theo mặc định:

```bash
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8003 uv run mssql-mcp-vn
```

## Cấu hình

```json
{
  "mcpServers": {
    "mssql-mcp-vn": {
      "command": "uvx",
      "args": ["mssql-mcp-vn==0.2.0"],
      "env": {
        "MSSQL_SERVER": "sql.internal.example",
        "MSSQL_USER": "mssql_mcp",
        "MSSQL_PASSWORD": "<secret-from-secret-store>",
        "MSSQL_PORT": "1433",
        "MSSQL_BACKUP_SQL_ROOT": "\\\\fileserver\\mssql-backups",
        "MSSQL_BACKUP_LOCAL_ROOT": "/srv/mssql-backups"
      }
    }
  }
}
```

`MSSQL_BACKUP_SQL_ROOT` là đường dẫn SQL Server nhìn thấy. `MSSQL_BACKUP_LOCAL_ROOT`
là cùng storage được mount trên máy Linux chạy MCP. MCP không tải file 10 GB qua TDS.

## Principal tối thiểu

Không chạy MCP bằng `sa`. Tạo login riêng, rồi cấp quyền trên từng database được phép
đọc/backup:

```sql
CREATE LOGIN [mssql_mcp] WITH PASSWORD = '<generate-and-store-separately>';
GO
USE [application_db];
CREATE USER [mssql_mcp] FOR LOGIN [mssql_mcp];
ALTER ROLE [db_datareader] ADD MEMBER [mssql_mcp];
ALTER ROLE [db_backupoperator] ADD MEMBER [mssql_mcp];
GRANT VIEW DEFINITION TO [mssql_mcp];
GO
```

`RESTORE VERIFYONLY` cần quyền `CREATE DATABASE` để đọc thông tin backup. Cấp cho user
trong `master` nếu tool backup phải verify:

```sql
USE [master];
CREATE USER [mssql_mcp] FOR LOGIN [mssql_mcp];
GRANT CREATE DATABASE TO [mssql_mcp];
GO
```

Đọc `percent_complete` từ `sys.dm_exec_requests` cần `VIEW SERVER STATE` (hoặc
`VIEW SERVER PERFORMANCE STATE` trên SQL Server 2022+). Nếu không cấp, backup vẫn chạy
nhưng phần trăm có thể là `null`; cân nhắc quyền này theo chính sách bảo mật.

## Runbook shared storage

SQL Server service account phải có quyền đọc/ghi trực tiếp share; quyền của principal
SQL không thay thế quyền filesystem.

### Windows SQL Server -> Samba/SMB trên Linux

1. Export một thư mục, ví dụ `/srv/mssql-backups`, bằng Samba.
2. Cấp ACL share và filesystem cho domain/service account chạy SQL Server.
3. Đặt `MSSQL_BACKUP_SQL_ROOT=\\fileserver\mssql-backups`.
4. Trên máy MCP, dùng chính thư mục local hoặc mount cùng share vào
   `/srv/mssql-backups`, rồi đặt `MSSQL_BACKUP_LOCAL_ROOT` tương ứng.
5. Dùng service account kiểm tra tạo/xóa một file thử trước khi gọi backup.

### Linux SQL Server -> NFS hoặc SMB mount

1. Mount NFS/SMB tại một path cố định trên host SQL Server, ví dụ
   `/mnt/mssql-backups`; service `mssql-server` phải đọc/ghi được.
2. Mount cùng export trên máy MCP tại `/srv/mssql-backups`.
3. Đặt `MSSQL_BACKUP_SQL_ROOT=/mnt/mssql-backups` và
   `MSSQL_BACKUP_LOCAL_ROOT=/srv/mssql-backups`.
4. Khai báo mount bền vững bằng cơ chế của hệ điều hành và kiểm tra mount đã sẵn sàng
   trước khi start MCP.

Tham khảo [Microsoft: backup devices](https://learn.microsoft.com/en-us/sql/relational-databases/backup-restore/backup-devices-sql-server),
[full database backup](https://learn.microsoft.com/en-us/sql/relational-databases/backup-restore/create-a-full-database-backup-sql-server),
và [RESTORE VERIFYONLY](https://learn.microsoft.com/en-us/sql/t-sql/statements/restore-statements-verifyonly-transact-sql).

## Vòng đời backup

Preflight yêu cầu database `ONLINE`, principal có `BACKUP DATABASE`, local root là
folder tuyệt đối có quyền đọc/ghi, và dung lượng trống ít nhất 110% allocated database
size. SQL ghi file duy nhất `*.bak.partial`; MCP chạy `RESTORE VERIFYONLY ... WITH
CHECKSUM`, rồi atomic rename thành `.bak` trên local mount.

MCP tự đọc `SERVERPROPERTY('EngineEdition')` trên connection của job. Backup bỏ
`COMPRESSION` khi edition là SQL Server Express để tránh lỗi 1844; `COPY_ONLY`,
`CHECKSUM` và `STATS = 5` luôn được giữ nguyên.

Registry job và khóa một-job chỉ sống trong process. Không restart MCP giữa chừng.
Phiên bản này không overwrite, cancel, retention, differential hoặc log backup. Khi lỗi,
chỉ file partial do job đó tạo bị xóa.

## So sánh schema

Hai database bắt buộc khác nhau và nằm trên instance đã cấu hình. `schema_name=null` quét
mọi user table schema. Kết quả được sort ổn định và phân loại `only_in_source`,
`only_in_target`, `different`; tool không sinh migration SQL. Views, procedures,
functions, triggers, users, permissions và system objects nằm ngoài phạm vi.

## Phát triển

```bash
cd uvx/mssql
pytest tests -v
ruff check src tests
ruff format --check src tests
mypy src
uv build
```

Fixture staging và 10 evaluation cố định nằm trong `evaluations/`.

## Changelog

### 0.2.0 - 2026-09-01

- Thêm full background `.bak` backup với preflight, DMV progress, checksum verify và
  atomic finalization.
- Thêm relational schema compare có filter và pagination ổn định.
- Khóa query tool về `SELECT`/read-only CTE và chặn `EXEC`/`INTO` cùng DDL/DML.
- Sửa transport thành `streamable-http`, bind mặc định `127.0.0.1`.
- Thêm fixture, evaluations, schema regression và unit tests.

### 0.1.7 - 2026-08-18

- Public MCP tools dùng flat arguments và có schema regression tests.
