Mcpql

🚀 MCPQL - SQL Server MCP

MCPQL 是一款全面的 模型上下文協議（MCP） 服務器，專為 SQL Server 數據庫操作而設計。該服務器通過 MCP 協議提供了 10 種強大的工具，可用於數據庫分析、對象發現和數據操作。

🚀 快速開始

前提條件

• Node.js 18 及以上版本和 npm
• 具備適當連接憑證的 SQL Server 數據庫
• 兼容 MCP 的客戶端（如 Claude Desktop、Cursor IDE 或任何 MCP 客戶端）

安裝與配置

選項 1：通過 GitHub 使用 npx（推薦）

無需安裝！只需配置您的 MCP 客戶端：

對於 Claude Desktop (claude_desktop_config.json)：

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "your_server",
        "DB_NAME": "your_database",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

對於 Cursor IDE：

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "your_server",
        "DB_NAME": "your_database",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

選項 2：本地開發安裝

1. 克隆並設置：

git clone https://github.com/hendrickcastro/MCPQL.git
cd MCPQL
npm install
npm run build

2. 配置數據庫連接： 創建一個 .env 文件，並填入您的數據庫憑證：

# 基本 SQL Server 連接
DB_AUTHENTICATION_TYPE=sql
DB_SERVER=localhost
DB_NAME=MyDatabase
DB_USER=sa
DB_PASSWORD=YourPassword123!
DB_PORT=1433
DB_ENCRYPT=false
DB_TRUST_SERVER_CERTIFICATE=true

3. 使用本地路徑配置 MCP 客戶端：

{
  "mcpServers": {
    "mcpql": {
      "command": "node",
      "args": ["path/to/MCPQL/dist/server.js"]
    }
  }
}

✨ 主要特性

MCPQL 為 SQL Server 數據庫操作提供了 10 種全面的工具：

1. 🏗️ 表分析 - mcp_table_analysis

完成表結構分析，包括列、鍵、索引和約束。

2. 📋 存儲過程分析 - mcp_sp_structure

分析存儲過程結構，包括參數、依賴項和源代碼。

3. 👀 數據預覽 - mcp_preview_data

預覽表數據，支持可選的過濾和行限制。

4. 📊 列統計信息 - mcp_get_column_stats

獲取特定列的全面統計信息。

5. ⚙️ 執行存儲過程 - mcp_execute_procedure

使用參數執行存儲過程並返回結果。

6. 🔍 執行 SQL 查詢 - mcp_execute_query

執行自定義 SQL 查詢，並進行全面的錯誤處理。

7. ⚡ 快速數據分析 - mcp_quick_data_analysis

進行快速統計分析，包括行數統計、列分佈和前幾個值。

8. 🔎 全面搜索 - mcp_search_comprehensive

根據名稱和定義在數據庫對象中進行搜索，支持可配置的搜索條件。

9. 🔗 對象依賴關係 - mcp_get_dependencies

獲取數據庫對象（表、視圖、存儲過程等）的依賴關係。

10. 🎯 示例值 - mcp_get_sample_values

從表的特定列中獲取示例值。

💻 使用示例

分析表

// 獲取完整的表結構
const analysis = await mcp_table_analysis({ 
  table_name: "dbo.Users" 
});

// 獲取快速數據概述
const overview = await mcp_quick_data_analysis({ 
  table_name: "dbo.Users",
  sample_size: 500
});

// 使用過濾器預覽表數據
const data = await mcp_preview_data({
  table_name: "dbo.Users",
  filters: { "Status": "Active", "Department": "IT" },
  limit: 25
});

查找數據庫對象

// 查找所有包含 "User" 的對象
const objects = await mcp_search_comprehensive({ 
  pattern: "User",
  search_in_names: true,
  search_in_definitions: false
});

// 查找查詢特定表的存儲過程
const procedures = await mcp_search_comprehensive({ 
  pattern: "FROM Users",
  object_types: ["PROCEDURE"],
  search_in_definitions: true
});

分析存儲過程

// 獲取完整的存儲過程分析
const spAnalysis = await mcp_sp_structure({ 
  sp_name: "dbo.usp_GetUserData" 
});

// 執行存儲過程
const result = await mcp_execute_procedure({
  sp_name: "dbo.usp_GetUserById",
  params: { "UserId": 123, "IncludeDetails": true }
});

數據分析

// 獲取列統計信息
const stats = await mcp_get_column_stats({
  table_name: "dbo.Users",
  column_name: "Age"
});

// 從列中獲取示例值
const samples = await mcp_get_sample_values({
  table_name: "dbo.Users",
  column_name: "Department",
  limit: 15
});

🔧 技術細節

環境變量與連接類型

MCPQL 支持多種 SQL Server 連接類型，並提供全面的配置選項：

🔐 身份驗證類型

將 DB_AUTHENTICATION_TYPE 設置為以下之一：

• sql - SQL Server 身份驗證（默認）
• windows - Windows 身份驗證
• azure-ad - Azure Active Directory 身份驗證

📋 完整的環境變量

連接配置示例

1. 🏠 SQL Server 本地（SQL 身份驗證）

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "localhost",
        "DB_NAME": "MyDatabase",
        "DB_USER": "sa",
        "DB_PASSWORD": "YourPassword123!",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

2. 🏢 SQL Server Express（命名實例）

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "localhost",
        "DB_INSTANCE_NAME": "SQLEXPRESS",
        "DB_NAME": "MyDatabase",
        "DB_USER": "sa",
        "DB_PASSWORD": "YourPassword123!",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

3. 🪟 Windows 身份驗證

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "windows",
        "DB_SERVER": "MYSERVER",
        "DB_NAME": "MyDatabase",
        "DB_DOMAIN": "MYDOMAIN",
        "DB_USER": "myuser",
        "DB_PASSWORD": "mypassword",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

4. ☁️ Azure SQL 數據庫（Azure AD 密碼）

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "azure-ad",
        "DB_SERVER": "myserver.database.windows.net",
        "DB_NAME": "MyDatabase",
        "DB_USER": "user@domain.com",
        "DB_PASSWORD": "userpassword",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "false"
      }
    }
  }
}

5. 🔐 Azure SQL 數據庫（服務主體）

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "azure-ad",
        "DB_SERVER": "myserver.database.windows.net",
        "DB_NAME": "MyDatabase",
        "DB_AZURE_CLIENT_ID": "your-client-id",
        "DB_AZURE_CLIENT_SECRET": "your-client-secret",
        "DB_AZURE_TENANT_ID": "your-tenant-id",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "false"
      }
    }
  }
}

6. 🔗 使用連接字符串

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_CONNECTION_STRING": "Server=localhost;Database=MyDatabase;User Id=sa;Password=YourPassword123!;Encrypt=false;TrustServerCertificate=true;"
      }
    }
  }
}

🚨 常見問題排查

連接問題

• “登錄失敗”：檢查用戶名/密碼。對於 Windows 身份驗證，請確保 DB_AUTHENTICATION_TYPE=windows
• “未找到服務器”：驗證服務器名稱和端口。對於 SQL Express，請添加 DB_INSTANCE_NAME
• “證書”錯誤：對於本地開發，設置 DB_TRUST_SERVER_CERTIFICATE=true
• 超時錯誤：增加 DB_TIMEOUT 或檢查網絡連接

SQL Server Express 設置

1. 在 SQL Server 配置管理器中啟用 TCP/IP 協議
2. 設置靜態端口（通常為 1433）或使用帶有瀏覽器服務的動態端口
3. 配置 Windows 防火牆以允許 SQL Server 流量
4. 對於默認的 Express 安裝，使用 DB_INSTANCE_NAME=SQLEXPRESS

Azure SQL 數據庫設置

1. 創建服務器防火牆規則以允許客戶端 IP
2. 服務器名稱使用格式：server.database.windows.net
3. 始終設置 DB_ENCRYPT=true 和 DB_TRUST_SERVER_CERTIFICATE=false
4. 對於服務主體身份驗證，在 Azure AD 中註冊應用並分配權限

🧪 測試

運行全面的測試套件：

npm test

測試套件包括對所有 10 種工具的全面測試，使用真實數據庫進行測試並實現了完全覆蓋。

🏗️ 架構

項目結構

MCPQL/
├── src/
│   ├── __tests__/          # 全面的測試套件
│   ├── tools/              # 模塊化工具實現
│   │   ├── tableAnalysis.ts      # 表分析工具
│   │   ├── storedProcedureAnalysis.ts  # 存儲過程分析工具
│   │   ├── dataOperations.ts     # 數據操作工具
│   │   ├── objectSearch.ts       # 搜索和發現工具
│   │   ├── types.ts              # 類型定義
│   │   └── index.ts              # 工具導出
│   ├── db.ts               # 數據庫連接管理
│   ├── server.ts           # MCP 服務器設置和處理程序
│   ├── tools.ts            # 工具定義和模式
│   └── mcp-server.ts       # 工具重新導出
├── dist/                   # 編譯後的 JavaScript 輸出
└── package.json           # 依賴項和腳本

關鍵特性

• ⚡ 連接池：高效的數據庫連接管理
• 🛡️ 強大的錯誤處理：全面的錯誤處理和驗證
• 📋 豐富的元數據：詳細的結果，包含全面的數據庫信息
• 🔧 靈活的配置：基於環境的配置
• 📊 優化的查詢：所有操作都採用高效的 SQL 查詢

📝 重要提示

⚠️ 重要提示

• 對象名稱：始終使用帶架構限定的名稱（例如，dbo.Users、api.Idiomas）
• 錯誤處理：所有工具都返回帶有成功/錯誤指示的結構化響應
• 類型安全：完全支持 TypeScript，並提供適當的類型定義
• 連接管理：自動連接池和重試邏輯
• 安全性：使用參數化查詢以防止 SQL 注入

🤝 貢獻

1. 分叉倉庫
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 進行更改並添加測試
4. 確保所有測試通過 (npm test)
5. 提交更改 (git commit -m 'Add amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打開拉取請求

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

🙏 致謝

• 使用 Model Context Protocol SDK 構建
• 使用 mssql 進行 SQL Server 連接
• 使用 Jest 進行全面測試

🏷️ 標籤與關鍵詞

數據庫： sql-server azure-sql database-analysis database-tools mssql t-sql database-management database-administration database-operations data-analysis

MCP 與 AI： model-context-protocol mcp-server mcp-tools ai-tools claude-desktop cursor-ide anthropic llm-integration ai-database intelligent-database

技術： typescript nodejs npm-package cli-tool database-client sql-client database-sdk rest-api json-api database-connector

特性： table-analysis stored-procedures data-preview column-statistics query-execution database-search object-dependencies schema-analysis data-exploration database-insights

部署： docker azure-deployment cloud-ready enterprise-ready production-ready scalable secure authenticated encrypted configurable

用例： database-development data-science business-intelligence database-migration schema-documentation performance-analysis data-governance database-monitoring troubleshooting automation

🎯 MCPQL 通過模型上下文協議提供全面的 SQL Server 數據庫分析和操作功能。非常適合數據庫管理員、開發人員以及任何使用 SQL Server 數據庫的人員！ 🚀