---

💡 一句話總結: 把這個 MCP 伺服器接上 Claude / Cursor,你的 AI 就從「對著幾百張表盲目試錯的實習生」變成「熟知 schema、會走最短 Join 路徑、且絕不越權的資深 DBA 搭檔」。

---

🎯 為什麼你需要「語意層」,而不是另一個 SQL 執行器?

把資料庫直接丟給 AI 的下場,每個試過的人都知道。傳統 SQL MCP 只給 AI 一把刀;我們給的是一整個腦。

😱 傳統 SQL MCP 的致命痛點	⚡ sqlserver-semantic-mcp 的解法
AI 盲目瞎猜 Join 條件,幻覺出不存在的外鍵,查詢結果一片混亂	🧭 BFS 圖形演算法走訪真實外鍵圖,find_join_path 自動探索兩張表之間的最短 Join 路徑(最多 5 hops)
每個問題都重複轟炸系統表(sys.*、INFORMATION_SCHEMA),拖垮線上資料庫	🚀 雙層 SQLite 快取 + 結構預熱:結構與語意分析全部本地持久化,毫秒級回應、線上 DB 零壓力,並由輕量 L1 探針自動偵測 schema 漂移、精準失效
AI 一個 UPDATE 忘了寫 WHERE,刪庫跑路不再是段子	🛡 JSON Policy 安全閘門(Guardrails):預設唯讀、強制 WHERE 子句、最大回傳/影響列數上限、schema/table 白名單——每一句 SQL 都先過安檢
面對上百張資料表,AI 在 token 海裡迷路,上下文爆炸	🧠 自動語意分類:每張表自動標記為 Fact / Dimension / Lookup / Bridge / Audit,欄位自動辨識審計欄、軟刪除欄——幫 AI 畫好重點再上場
Schema 改了,AI 還在用三天前的舊認知回答	🔄 三重 Hash 版本控制 + Catalog 指紋探針:欄位型別從 nvarchar(4) 改成 nvarchar(10) 都逃不過,變更自動連鎖刷新,永不過期、也永不浪費重抓

🎯 結果: 更少的 token 消耗、更少的錯誤重試、更快的正確答案——以及一個敢真正放進生產環境的 AI 資料庫工具。

---

🚀 3 分鐘極速上手

不需要 git clone、不需要建虛擬環境、不需要安裝任何東西到專案裡。只要 uv(一行指令安裝:curl -LsSf https://astral.sh/uv/install.sh | sh),uvx 會自動下載、快取並啟動伺服器。

⚠️ 把範例中的 localhost / YourDatabase / sa / YourPassword 換成你的 SQL Server 連線資訊即可。

🖥 Claude Desktop(複製貼上即用)

編輯設定檔:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sqlserver-semantic": {
      "command": "uvx",
      "args": ["sqlserver-semantic-mcp"],
      "env": {
        "SEMANTIC_MCP_MSSQL_SERVER": "localhost",
        "SEMANTIC_MCP_MSSQL_DATABASE": "YourDatabase",
        "SEMANTIC_MCP_MSSQL_USER": "sa",
        "SEMANTIC_MCP_MSSQL_PASSWORD": "YourPassword"
      }
    }
  }
}

存檔後重啟 Claude Desktop —— 完成。✅

⌨️ Cursor(複製貼上即用)

在專案根目錄建立 .cursor/mcp.json(或全域 ~/.cursor/mcp.json):

{
  "mcpServers": {
    "sqlserver-semantic": {
      "command": "uvx",
      "args": ["sqlserver-semantic-mcp"],
      "env": {
        "SEMANTIC_MCP_MSSQL_SERVER": "localhost",
        "SEMANTIC_MCP_MSSQL_DATABASE": "YourDatabase",
        "SEMANTIC_MCP_MSSQL_USER": "sa",
        "SEMANTIC_MCP_MSSQL_PASSWORD": "YourPassword"
      }
    }
  }
}

🤖 Claude Code CLI(一行指令)

claude mcp add sqlserver-semantic -- uvx sqlserver-semantic-mcp \
  -e SEMANTIC_MCP_MSSQL_SERVER=localhost \
  -e SEMANTIC_MCP_MSSQL_DATABASE=YourDatabase \
  -e SEMANTIC_MCP_MSSQL_USER=sa \
  -e SEMANTIC_MCP_MSSQL_PASSWORD=YourPassword

🧪 30 秒煙霧測試(可選)

SEMANTIC_MCP_MSSQL_SERVER=localhost \
SEMANTIC_MCP_MSSQL_DATABASE=YourDatabase \
SEMANTIC_MCP_MSSQL_USER=sa \
SEMANTIC_MCP_MSSQL_PASSWORD=YourPassword \
  uvx sqlserver-semantic-mcp

看到快取初始化與工具註冊的啟動日誌,就代表一切就緒。接著對你的 AI 說:

「幫我找出 Orders 和 Customers 之間怎麼 Join,然後算出上個月的客單價。」

然後看著它第一次就答對。🎉

---

🛠 殺手級特性與工具箱

29 個 MCP 工具,分為三大核心模組——每一個都為「讓 AI 少走彎路」而生:

🧭 1. 探索與語意模組 —— 讓 AI 真正「看懂」資料庫

工具	它為你做什麼
🔍 discover_relevant_tables	用自然語言關鍵字直達相關資料表,告別人肉翻 schema
🧬 classify_table	自動判定 Fact / Dimension / Lookup / Bridge / Audit,AI 秒懂這張表的角色
🗺 find_join_path	BFS 走訪外鍵圖,自動算出兩張表之間的最短 Join 鏈——不再瞎猜
🤝 summarize_table_for_joining	一次打包主鍵、Join 候選欄、常用篩選欄,為撰寫查詢量身整理
🪜 get_dependency_chain	沿外鍵展開整條相依鏈,影響分析一目了然
📜 describe_view / describe_procedure	檢視表與預存程序的定義、相依物件、讀寫拆解(哪些表被讀、哪些被寫)

🚀 2. 效能與快取模組 —— 毫秒級回應,線上 DB 零負擔

工具 / 機制	它為你做什麼
⚡ 雙層 SQLite 快取(內建)	結構快取 + 語意快取全部本地持久化,重啟免重抓(cache-first 啟動)
📡 L1 Catalog 指紋探針(內建、全自動)	純 catalog 查詢、毫秒級偵測 schema 漂移——欄位型別、長度、索引、檢視表內文變更全部捕捉,只刷新真正變動的表
🔄 refresh_schema_cache	一鍵強制全量刷新,語意分析自動連鎖重算
📦 bundle_context_for_next_step	把下一步需要的上下文一次打包,大幅節省 token
📊 get_tool_metrics	內建每個工具的回應大小量測,token 成本看得見

🛡 3. 安全與執行防護模組 —— DBA 敢簽核的 AI 工具

工具	它為你做什麼
🚦 plan_or_execute_query	智慧路由:安全的查詢直接執行,危險的自動轉入計畫與確認流程
🕵️ validate_sql_against_policy	執行前先驗證:操作權限、WHERE 強制、列數上限——任何一關不過就攔下
⚖️ estimate_execution_risk	量化這句 SQL 的風險等級,先看清楚再動手
👀 preview_safe_query	不動資料、先看執行計畫與樣本,安心預演
✅ run_safe_query	政策閘門背書下的查詢執行,row cap 與 timeout 全程護航

---

🛡 生產級安全配置

這是讓企業主管與 DBA 點頭的章節。 預設行為就是唯讀——AI 連一個 UPDATE 都碰不到,除非你明確授權。

環境變數防護(開箱即生效)

SEMANTIC_MCP_MAX_ROWS_RETURNED=1000    # SELECT 回傳列數上限
SEMANTIC_MCP_MAX_ROWS_AFFECTED=100     # DML 影響列數上限(超過即拒絕)
SEMANTIC_MCP_QUERY_TIMEOUT=30          # 查詢逾時秒數
SEMANTIC_MCP_PROBE_INTERVAL_S=60       # Schema 漂移探針節流窗口

JSON Policy 安全閘門(進階分級授權)

用一個 JSON 檔定義 AI 的權限邊界,透過 SEMANTIC_MCP_POLICY_FILE 載入:

{
  "active_profile": "readonly",
  "profiles": {
    "readonly": {
      "operations": { "select": true },
      "constraints": { "max_rows_returned": 1000, "query_timeout_seconds": 30 }
    },
    "read_write_safe": {
      "operations": { "select": true, "insert": true, "update": true },
      "constraints": {
        "require_where_for_update": true,
        "max_rows_affected": 100
      }
    }
  }
}

安全設計三原則:

• 🔒 預設唯讀 —— policy 檔遺失或損壞時,自動回退為內建唯讀模式,絕不裸奔
• 🚧 強制 WHERE —— require_where_for_update 讓「忘了寫 WHERE 的 UPDATE」在執行前就被攔截
• 🎯 範圍白名單 —— schema / table 層級的允許與拒絕清單,敏感表 AI 連看都看不到

完整 policy 範例請見 config/policy.example.json。

---

🧩 它是怎麼運作的?

AI Agent (Claude / Cursor / Codex)
        │  MCP (stdio)
        ▼
┌─────────────────────────────────────────────┐
│  sqlserver-semantic-mcp                     │
│                                             │
│  🧠 語意層    分類 / Join 路徑 / 相依分析     │
│  🛡 政策閘門  唯讀預設 / WHERE 強制 / 列數上限 │
│  ⚡ 快取層    雙層 SQLite + L1 漂移探針        │
└─────────────────┬───────────────────────────┘
                  │  只在必要時查詢
                  ▼
            🗄 SQL Server (2017+)

• 三重 Hash 版本控制 —— 結構 / 物件 / 註解三組指紋,任何變更精準觸發失效
• 逐表精準失效 —— 只有真正變動的表重新分析,其餘快取原封不動
• 背景漸進填入 —— 語意分析在背景批次收斂,啟動永遠是秒級

---

📚 想深入了解?

文件	內容
📖 README.en.md	完整英文技術文件:架構、29 個工具全覽、環境變數、部署、疑難排解
📖 README.zh-TW.md	完整繁體中文技術文件
🛡 config/policy.example.json	三段式權限 Policy 範本(readonly / read_write_safe / admin)

---

⭐ 喜歡這個專案?

如果它幫你的 AI 第一次就寫對 Join、或幫你的 DBA 睡了個好覺——

請點一下右上角的 Star ⭐,讓更多人找到它!

回報問題 · 貢獻指南 · MIT License © LukeStackLab