PGMCP - PostgreSQL Model Context Protocol Server

PGMCP, AI asistanlarını doğal dil sorgularıyla herhangi bir PostgreSQL veritabanına bağlar. Düz İngilizce sorular sorun ve otomatik streaming ve sağlam hata işleme ile yapılandırılmış SQL sonuçları alın.

Çalışır: Cursor, Claude Desktop, VS Code uzantıları ve herhangi bir MCP-uyumlu istemci

Hızlı Başlangıç

PGMCP, mevcut PostgreSQL veritabanınıza bağlanır ve doğal dil sorgularıyla AI asistanlarının erişebilmesi için bunu uygun hale getirir.

Önkoşullar

• PostgreSQL veritabanı (şemanız olan mevcut bir veritabanı)
• OpenAI API anahtarı (isteğe bağlı, AI tarafından desteklenen SQL oluşturma için)

Temel Kullanım

# Ortam değişkenlerini ayarlayın
export DATABASE_URL="postgres://user:password@localhost:5432/your-existing-db"
export OPENAI_API_KEY="your-api-key"  # İsteğe bağlı

# Sunucuyu çalıştırın (önceden derlenmiş ikili dosya kullanarak)
./pgmcp-server

# Başka bir terminalde istemciyi test edin
./pgmcp-client -ask "What tables do I have?" -format table
./pgmcp-client -ask "Who is the customer that has placed the most orders?" -format table
./pgmcp-client -search "john" -format table

Nasıl çalıştığı aşağıda gösterilmektedir:

👤 Kullanıcı / AI Asistanı
         │
         │ "Who are the top customers?"
         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Herhangi bir MCP İstemci                 │
│                                                             │
│  PGMCP CLI  │  Cursor  │  Claude Desktop  │  VS Code  │ ... │
│  JSON/CSV   │  Chat    │  AI Assistant    │  Editor   │     │
└─────────────────────────────────────────────────────────────┘
         │
         │ Streamable HTTP / MCP Protocol
         ▼
┌─────────────────────────────────────────────────────────────┐
│                    PGMCP Sunucusu                           │
│                                                             │
│  🔒 Güvenlik    🧠 AI Motoru      🌊 Streaming               │
│  • Input Valid  • Schema Cache    • Auto-Pagination         │
│  • Audit Log    • OpenAI API      • Memory Management       │
│  • SQL Guard    • Error Recovery  • Connection Pool         │
└─────────────────────────────────────────────────────────────┘
         │
         │ Salt Okunur SQL Sorguları
         ▼
┌─────────────────────────────────────────────────────────────┐
│                PostgreSQL Veritabanınız                     │
│                                                             │
│  Herhangi bir Şema: E-Commerce, Analitik, CRM, vb.           │
│  Tablolar • Views • İndeksler • İşlevler                    │
└─────────────────────────────────────────────────────────────┘

Dış AI Hizmetleri:
OpenAI API • Anthropic • Yerel LLM'ler (Ollama, vb.)

Temel Avantajlar:
✅ HERHANGİ bir PostgreSQL veritabanıyla çalışır (şema hakkında varsayım yok)
✅ Şema değişiklikleri gerekli değildir  
✅ Salt okunur erişim (%100 güvenli)
✅ Büyük sonuçlar için otomatik streaming
✅ Zeki sorgu anlama (tekil vs çoğul)
✅ Sağlam hata işleme (zarif AI hatası kurtarması)
✅ PostgreSQL büyük/küçük harf duyarlılığı desteği (karışık duruş tabloları)
✅ Üretim hazırlığı güvenliği ve performansı
✅ Evrensel veritabanı uyumluluğu
✅ Çoklu çıktı formatları (tablo, JSON, CSV)
✅ Tüm sütunlarda serbest metin araması
✅ Kimlik doğrulama desteği
✅ Kapsamlı test paketi

Özellikler

• Doğal Dilden SQL'e: Sorularınızı düz İngilizce sorun
• Otomatik Streaming: Büyük sonuç kümelerini otomatik olarak işler
• Güvenli Salt Okunur Erişim: Herhangi bir yazma işlemini önler
• Metin Araması: Tüm metin sütunlarında arama yapın
• Çoklu Çıktı Formatları: Tablo, JSON ve CSV
• PostgreSQL Büyük/Küçük Harf Duyarlılığı: Karışık duruş tablo adlarını doğru şekilde işler
• Evrensel Uyumluluk: Herhangi bir PostgreSQL veritabanıyla çalışır

Ortam Değişkenleri

Gerekli:

• DATABASE_URL: Mevcut veritabanınıza PostgreSQL bağlantı dizesi

İsteğe bağlı:

• OPENAI_API_KEY: AI tarafından desteklenen SQL oluşturma için OpenAI API anahtarı
• OPENAI_MODEL: Kullanılacak model (varsayılan: "gpt-4o-mini")
• HTTP_ADDR: Sunucu adresi (varsayılan: ":8080")
• HTTP_PATH: MCP endpoint yolu (varsayılan: "/mcp")
• AUTH_BEARER: Kimlik doğrulama için bearer token

Kurulum

Önceden Derlenmiş İkili Dosyaları İndirin

1. GitHub Yayınları sayfasına gidin
2. Platformunuz için ikili dosyayı indirin (Linux, macOS, Windows)
3. Çıkartın ve çalıştırın:

# macOS/Linux için örnek
tar xzf pgmcp_*.tar.gz
cd pgmcp_*
./pgmcp-server

Alternatif Seçenekler

# Homebrew (macOS/Linux) - İlk yayından sonra kullanılabilir
brew tap subnetmarco/homebrew-tap
brew install pgmcp

# Kaynaktan derleyin
go build -o pgmcp-server ./server
go build -o pgmcp-client ./client

Docker/Kubernetes

# Docker
docker run -e DATABASE_URL="postgres://user:pass@host:5432/db" \
  -p 8080:8080 ghcr.io/subnetmarco/pgmcp:latest

# Kubernetes (tam manifestler için examples/ dizinine bakın)
kubectl create secret generic pgmcp-secret \
  --from-literal=database-url="postgres://user:pass@host:5432/db"
kubectl apply -f examples/k8s/

Hızlı Başlangıç

# Veritabanını ayarlayın (isteğe bağlı - herhangi bir mevcut PostgreSQL veritabanıyla çalışır)
export DATABASE_URL="postgres://user:password@localhost:5432/mydb"
psql $DATABASE_URL < schema.sql

# Sunucuyu çalıştırın
export OPENAI_API_KEY="your-api-key"
./pgmcp-server

# İstemciyle test edin
./pgmcp-client -ask "Who is the user that places the most orders?" -format table
./pgmcp-client -ask "Show me the top 40 most reviewed items in the marketplace" -format table

Ortam Değişkenleri

Gerekli:

• DATABASE_URL: PostgreSQL bağlantı dizesi

İsteğe bağlı:

• OPENAI_API_KEY: SQL oluşturma için OpenAI API anahtarı
• OPENAI_MODEL: Kullanılacak model (varsayılan: "gpt-4o-mini")
• HTTP_ADDR: Sunucu adresi (varsayılan: ":8080")
• HTTP_PATH: MCP endpoint yolu (varsayılan: "/mcp")
• AUTH_BEARER: Kimlik doğrulama için bearer token

Kullanım Örnekleri

# Doğal dilde sorular sorun
./pgmcp-client -ask "What are the top 5 customers?" -format table
./pgmcp-client -ask "How many orders were placed today?" -format json

# Tüm metin alanlarında arama yapın
./pgmcp-client -search "john" -format table

# Aynı anda birden çok soru
./pgmcp-client -ask "Show tables" -ask "Count users" -format table

# Farklı çıktı formatları
./pgmcp-client -ask "Export all data" -format csv -max-rows 1000

Örnek Veritabanı

Proje iki şema içerir:

• schema.sql: 5.000+ kayıtlı tam Amazon benzeri pazaryeri
• schema_minimal.sql: Karışık duruş "Categories" tablosu ile minimal test şeması

Temel özellikler:

• Karışık duruş tablo adları ("Categories") büyük/küçük harf duyarlılığını test etmek için
• Bileşik birincil anahtarlar (order_items) AI varsayımlarını test etmek için
• Gerçekçi ilişkiler ve veri türleri

Kendi veritabanınızı kullanın:

export DATABASE_URL="postgres://user:pass@host:5432/your_db"
./pgmcp-server
./pgmcp-client -ask "What tables do I have?"

AI Hata İşleme

AI yanlış SQL oluşturduğunda, PGMCP bunu zarif bir şekilde işler:

{
  "error": "Column not found in generated query",
  "suggestion": "Try rephrasing your question or ask about specific tables",
  "original_sql": "SELECT non_existent_column FROM table..."
}

Çökmek yerine sistem yararlı geri bildirim sağlar ve çalışmaya devam eder.

MCP Entegrasyonu

Cursor Entegrasyonu

# Sunucuyu başlatın
export DATABASE_URL="postgres://user:pass@localhost:5432/your_db"
./pgmcp-server

Cursor ayarlarına ekleyin:

{
  "mcp.servers": {
    "pgmcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8080/mcp"
      }
    }
  }
}

Claude Desktop Entegrasyonu

~/.config/claude-desktop/claude_desktop_config.json düzenleyin:

{
  "mcpServers": {
    "pgmcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8080/mcp"
      }
    }
  }
}

API Tools

• ask: Doğal dil sorularından → otomatik streaming ile SQL sorgularına
• search: Tüm veritabanı metin sütunlarında serbest metin araması
• stream: Pagination ile çok büyük sonuç kümeleri için gelişmiş streaming

Güvenlik Özellikleri

• Salt Okunur Zorlama: Yazma işlemlerini engeller (INSERT, UPDATE, DELETE, vb.)
• Sorgu Zaman Aşımları: Uzun çalışan sorguları önler
• Giriş Doğrulaması: Tüm kullanıcı girdisini sanitize eder ve doğrular
• İşlem Yalıtımı: Tüm sorgular salt okunur işlemlerde çalışır

Test Etme

# Birim testleri
go test ./server -v

# Entegrasyon testleri (PostgreSQL gereklidir)
go test ./server -tags=integration -v

Lisans

Apache 2.0 - Ayrıntılar için LICENSE dosyasına bakın.

İlgili Projeler

• Model Context Protocol - Temel protokol spesifikasyonu
• MCP Go SDK - MCP'nin Go uygulaması

---

PGMCP, PostgreSQL veritabanınızı salt okunur erişim kontrolleriyle güvenliği koruyarak AI asistanlarına doğal dil aracılığıyla erişilebilir hale getirir.