Mssql

MSSQL’e Model Context Protocol (MCP) üzerinden güvenli bağlanan, STDIO modunda çalışan bir sunucudur.
Claude Desktop (ve MCP uyumlu diğer istemciler) tarafından harici bir tool olarak başlatılır.

NL→SQL: doğal dilde sor — Claude şemayı (discover_schema) kullanarak SQL üretir ve run_sql_safe ile çalıştırır.

---

✨ Özellikler

• connect_db — Ortam değişkenleriyle MSSQL bağlantısını dener (sağlık kontrolü).
• discover_schema — INFORMATION_SCHEMA tabanlı tablo/kolon keşfi; basit heuristiklerle date_cols, measures, dims etiketleri üretir.
• run_sql_safe — Tek SELECT ifadesini çalıştırır. DDL/DML ve çoklu ifadeler engellenir. Otomatik TOP 5000 enjekte edilir (sorguda varsa dokunmaz).

🛡️ Guardrails: DROP/UPDATE/INSERT/MERGE/EXEC vb. yasak; ;, --, /* */ gibi çoklu ifade/yorum kalıpları reddedilir; 15 sn timeout.

---

🧰 Gereksinimler

• Node.js 18+ (öneri: 20+)
• MSSQL (lokal / Docker / uzak / Azure SQL)

---

🔧 Kurulum

git clone https://github.com/ismailcankaratas/mcp-mssql.git
cd mcp-mssql
npm install

.env oluştur (repo kökünde):

MSSQL_HOST=localhost
MSSQL_PORT=1433
MSSQL_DB=YourDatabase
MSSQL_USER=readonly_login
MSSQL_PWD=ReadOnly!123

Geliştirmede encrypt=true ve trustServerCertificate=true varsayılan. Üretimde geçerli sertifika ile encrypt=true kullanın.

---

▶️ Çalıştırma

Geliştirme (TSX ile)

npm run dev

Build & Start

npm run build
npm start

---

🧪 Hızlı Bağlantı Testi

npx tsx src/test_local.ts

Beklenen:

OK: [ { current_db: "...", version: "Microsoft SQL Server 2022 ..." } ]

---

🖥️ Claude Desktop Entegrasyonu

Config dosyası (claude_desktop_config.json) örneği:

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/dist/server.js"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_PORT": "1433",
        "MSSQL_DB": "YourDatabase",
        "MSSQL_USER": "readonly_login",
        "MSSQL_PWD": "ReadOnly!123"
      }
    }
  }
}

Geliştirmede TS kaynakla koşmak istersen Command: "tsx", Args: ["src/server.ts"] kullanabilirsin.

---

🧭 Claude içinde kullanım örnekleri

• Bağlantı testi

  tool: connect_db {}
  

• Şemayı keşfet

  tool: discover_schema {}
  

• Güvenli sorgu çalıştır

  tool: run_sql_safe {"sql":"SELECT TOP 5 name FROM sys.databases ORDER BY name"}
  

NL→SQL: doğal dilde sor — Claude şemayı (discover_schema) kullanarak SQL üretir ve run_sql_safe ile çalıştırır.

---

🔒 Güvenlik Notları

• Üretimde salt-okuma kullanıcı (db_datareader) kullanın.
• run_sql_safe yalnızca tek bir SELECT’e izin verir; DDL/DML ve çoklu ifadeler reddedilir.
• Maksimum satır sayısı için TOP otomatik enjekte edilir (varsayılan: 5000).
• Sorgu süresi varsayılan 15s timeout ile sınırlıdır.
• .env ve gizli bilgileri asla versiyona eklemeyin.

---

🩺 Sorun Giderme

• ENOTFOUND / ECONNREFUSED / ETIMEDOUT → Host/port doğru mu? Docker portu açık mı?
• ELOGIN → Kullanıcı/parola doğru mu? DB’de db_datareader yetkisi var mı?
• TLS uyarısı (SNI) → IP yerine MSSQL_HOST=localhost kullanın veya sertifika tanımlayın.
• discover_schema boş → DB’de tablo yok ya da kullanıcı INFORMATION_SCHEMA’ya erişemiyor.

---

📂 Proje Yapısı

src/
  db.ts         # MSSQL bağlantısı ve query helper
  schema.ts     # INFORMATION_SCHEMA keşfi + heuristik etiketler
  server.ts     # MCP server (connect_db, discover_schema, run_sql_safe)
  test_local.ts # MSSQL bağlantı smoke testi

---

📄 Lisans

MIT