# mcp-mssql — Claude için MSSQL MCP Sunucusu

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

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

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

```env
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)
```bash
npm run dev
```

### Build & Start
```bash
npm run build
npm start
```

---

## 🧪 Hızlı Bağlantı Testi

```bash
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:**
```json
{
  "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