mssql-mcp-vn 0.1.2

High-performance MSSQL MCP Server

MSSQL MCP Server

Model Context Protocol (MCP) Server để tương tác với cơ sở dữ liệu Microsoft SQL Server. Server này cho phép các AI agent tự động quét toàn bộ danh sách database, đọc thông tin schema và thực thi các câu lệnh truy vấn (read-only) một cách an toàn.

Tính năng

🗄️ Quản lý Đa Cơ Sở Dữ Liệu (Multi-Database Auto-Scan)

• mssql_list_databases: Tự động kết nối đến server và quét danh sách toàn bộ các cơ sở dữ liệu đang có (trạng thái ONLINE).
• Các công cụ thao tác đều hỗ trợ tham số database_name để AI có thể tự do chỉ định database cần truy vấn mà không cần anh cấu hình từng cái một.

🔍 Thực thi truy vấn (Query Execution)

• mssql_execute_query: Chạy các câu lệnh SQL trên một database chỉ định.
• An toàn là trên hết (Safety First): Chỉ cho phép các thao tác chỉ đọc (SELECT, WITH, EXEC, SHOW).
• Danh sách từ khóa cấm (Keyword Blacklist): Tự động chặn bất kỳ câu truy vấn nào chứa các từ khóa phá hoại như DROP, DELETE, UPDATE, INSERT, ALTER, hoặc TRUNCATE.

📊 Khám phá Schema (Schema Exploration)

• mssql_list_tables: Liệt kê tất cả các bảng trong một schema cụ thể (mặc định là dbo).
• mssql_describe_table: Lấy metadata chi tiết cho các cột của một bảng cụ thể (kiểu dữ liệu, cho phép null, độ dài tối đa).

Cài đặt

Yêu cầu hệ thống (Prerequisites)

• Python 3.12+
• uv (khuyên dùng) hoặc pip
• ODBC Driver cho SQL Server (ví dụ: ODBC Driver 17 for SQL Server) đã được cài đặt trên máy host.

Thiết lập (Setup)

# Di chuyển vào thư mục của server
cd servers/mssql

# Cài đặt các thư viện phụ thuộc bằng uv
uv sync

Cấu hình

Server này đọc cấu hình từ các biến môi trường (environment variables). Anh KHÔNG CẦN chỉ định database cụ thể, chỉ cần cấp thông tin máy chủ để server tự quét:

{
  "mcpServers": {
    "mssql-mcp-vn": {
      "command": "uvx",
      "args": [
        "mssql-mcp-vn"
      ],
      "env": {
        "MSSQL_SERVER": "localhost",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_PORT": "1433",
        "MSSQL_DRIVER": "ODBC Driver 17 for SQL Server"
      }
    }
  }
}

Các trường cấu hình (Configuration Fields)

• MSSQL_SERVER (bắt buộc): Hostname hoặc địa chỉ IP của Server.
• MSSQL_USER (bắt buộc): Tên đăng nhập (username) SQL Server.
• MSSQL_PASSWORD (bắt buộc): Mật khẩu đăng nhập SQL Server.
• MSSQL_PORT (tùy chọn): Cổng kết nối (mặc định là 1433).
• MSSQL_DRIVER (tùy chọn): Tên của ODBC driver (mặc định là "ODBC Driver 17 for SQL Server").

Chạy Server (Run Server)

Chạy như một MCP Server (Stdio)

uv run src/mssql_mcp_server.py

Cấu hình thành một gói Package để chạy qua UVX (Optional)

Nếu anh muốn đẩy lên mạng và chạy trực tiếp bằng uvx mssql-mcp-vn (hoặc kéo từ Github):

• Trong pyproject.toml đã khai báo [project.scripts].
• Lệnh sẽ tự động gọi hàm main() trong src/mssql_mcp_server.py.
• Anh có thể đẩy source code lên Github và chạy bằng: uvx git+https://github.com/username/mssql-mcp-vn.git

Xử lý lỗi (Error Handling)

Tất cả các công cụ đều trả về chuỗi định dạng JSON hoặc thông báo lỗi rõ ràng:

• Lỗi xác thực sẽ trả về lỗi kết nối (connection errors).
• Các câu lệnh phá hoại sẽ trả về một thông báo lỗi rõ ràng "Error: Detected potentially destructive keywords in query."
• Phản hồi bình thường sẽ bao gồm số lượng dòng, tiêu đề cột và mảng dữ liệu được định dạng phù hợp để LLM có thể đọc hiểu.