Apache Doris

resmi

Apache Doris için MCP Sunucusu, MPP tabanlı gerçek zamanlı bir veri ambarı.

GitHub

314

Apache Doris MCP ile neler yapabilirsiniz?

SQL sorguları çalıştırın — AI'den, exec_query kullanarak Doris veritabanınızda bir SQL ifadesi yürütmesini isteyin; isteğe bağlı olarak bir katalog, veritabanı veya satır sınırı belirtebilirsiniz.
Veritabanı meta verilerini keşfedin — katalogları, veritabanlarını ve tabloları get_catalog_list, get_db_list ve get_db_table_list ile listeleyin; ardından şemaları, indeksleri ve yorumları get_table_schema, get_table_indexes, get_table_comment ve get_table_column_comments aracılığıyla inceleyin.
Sorgu performansını analiz edin — yavaş veya karmaşık sorguları teşhis etmek için get_sql_explain ve get_sql_profile ile yürütme planlarını ve profillerini alın.
Küme sağlığını izleyin — gerçek zamanlı ve geçmiş bellek istatistiklerini, izleme metrik tanımlarını ve gerçek düğüm metriklerini get_realtime_memory_stats, get_historical_memory_stats, get_monitoring_metrics_info ve get_monitoring_metrics_data kullanarak alın.
Denetim ve erişim modellerini inceleyin — son denetim günlüklerini get_recent_audit_logs ile gözden geçirin ve kullanıcı erişim davranışını analyze_data_access_patterns aracılığıyla analiz edin.
Arrow Flight SQL ile yüksek performanslı sorgular çalıştırın — büyük sonuçlu sorguları exec_adbc_query ile yürütün ve ADBC bağlantı durumunu get_adbc_connection_info ile kontrol edin.

Dokümantasyon

Doris MCP Sunucusu

Doris MCP (Model Bağlam Protokolü) Sunucusu, Python ve FastAPI ile oluşturulmuş bir arka uç hizmetidir. MCP'yi uygulayarak istemcilerin tanımlı "Araçlar" aracılığıyla onunla etkileşime girmesine olanak tanır. Öncelikle Apache Doris veritabanlarına bağlanmak için tasarlanmıştır ve doğal dil sorgularını SQL'e dönüştürme (NL2SQL), sorgu yürütme ve meta veri yönetimi ile analizi gibi görevler için Büyük Dil Modellerinden (LLM'ler) potansiyel olarak yararlanır.

🚀 v0.6.0 Sürümündeki Yenilikler

🔐 Kurumsal Kimlik Doğrulama Sistemi: Kapsamlı Token, JWT ve OAuth kimlik doğrulama desteği ile devrim niteliğinde token'a bağlı veritabanı yapılandırması, ayrıntılı kontrol anahtarları ve kurumsal düzeyde güvenlik varsayılanları ile güvenli çok kiracılı erişim sağlar
⚡ Anında Veritabanı Doğrulaması: Bağlantı anında gerçek zamanlı veritabanı yapılandırma doğrulaması, sorgu zamanı engellemeyi ortadan kaldırır ve geçersiz yapılandırmalar için anında geri bildirim sağlar - geç aşama bağlantı hatalarının %100 ortadan kaldırılmasını sağlar
🔄 Sıcak Yeniden Yükleme Yapılandırma Yönetimi: tokens.json dosyasının akıllı sıcak yeniden yüklemesi, otomatik token yeniden doğrulaması ve geri alma mekanizmalarıyla kapsamlı hata işleme ile sıfır kesinti süreli yapılandırma güncellemeleri
🏗️ Gelişmiş Bağlantı Mimarisi: Bağlantı ek yükünde %60 azalma, akıllı havuz yeniden oluşturma ve otomatik kaynak yönetimi ile oturum önbellekleme ve bağlantı havuzu optimizasyonu
🌐 Çoklu Çalışan Ölçeklenebilirliği: Durumsuz çoklu çalışan mimarisi, verimli yük dağıtımı ve kurumsal düzeyde eşzamanlı işleme yetenekleri ile gerçek yatay ölçeklendirme
🔒 Gelişmiş Güvenlik Çerçevesi: Anında doğrulama, rol tabanlı izinler ve gelişmiş enjeksiyon algılama desenleri ile kapsamlı erişim kontrolü ve SQL güvenlik doğrulaması
🛠️ Birleşik Yapılandırma Sistemi: Uygun komut satırı önceliği, Docker uyumluluğu iyileştirmeleri ve platformlar arası dağıtım desteği ile kolaylaştırılmış yapılandırma yönetimi
📊 Token Yönetim Panosu: Kurumsal token yönetişimi için oluşturma, iptal etme, istatistikler ve kapsamlı denetim izleri ile eksiksiz token yaşam döngüsü yönetimi
🌐 Web Tabanlı Yönetim Arayüzü: Sezgisel pano, veritabanı bağlama yapılandırması, gerçek zamanlı işlemler ve kurumsal düzeyde erişim kontrolleri ile güvenli yalnızca localhost token yönetimi

🚀 Büyük Kilometre Taşı: v0.6.0, platformu sıfır kesinti süreli işlemler (sıcak yeniden yükleme + anında doğrulama + çoklu çalışan ölçeklendirme), gelişmiş güvenlik kontrolleri ve kapsamlı token'a bağlı veritabanı yapılandırması ile üretime hazır kurumsal kimlik doğrulama ve veritabanı yönetim sistemi olarak konumlandırır - kurumsal veri platformu yeteneklerinde temel bir ilerlemeyi temsil eder.

v0.5.1'den Ayrıca Dahil Edilenler

🔥 Kritik at_eof Bağlantı Düzeltmesi: Akıllı sağlık izleme ve kendi kendini iyileştiren kurtarma ile bağlantı havuzu hatalarının tamamen ortadan kaldırılması
🔧 Kurumsal Günlük Sistemi: Otomatik temizleme ve milisaniye hassasiyetinde zaman damgaları ile seviye tabanlı dosya ayırma
📊 Gelişmiş Veri Analitiği Paketi: Kalite analizi, köken takibi ve performans izleme dahil 7 kurumsal düzeyde veri yönetişim aracı
🏃‍♂️ Yüksek Performanslı ADBC Entegrasyonu: Büyük veri kümeleri için 3-10 kat performans iyileştirmesi ile Apache Arrow Flight SQL desteği
⚙️ Gelişmiş Yapılandırma Yönetimi: Akıllı parametre doğrulaması ile eksiksiz ADBC yapılandırma sistemi

Temel Özellikler

MCP Protokol Uygulaması: Araç çağrılarını, kaynak yönetimini ve bilgi istemi etkileşimlerini destekleyen standart MCP arayüzleri sağlar.
Akışkan HTTP İletişimi: Optimum performans ve güvenilirlik için hem istek/yanıt hem de akış iletişimini destekleyen birleşik HTTP uç noktası.
Stdio İletişimi: Cursor gibi MCP istemcileriyle doğrudan entegrasyon için standart giriş/çıkış modu.
Kurumsal Düzeyde Mimari: Kapsamlı işlevselliğe sahip modüler tasarım:
- Araç Yöneticisi: Birleşik arayüzlerle merkezi araç kaydı ve yönlendirme (doris_mcp_server/tools/tools_manager.py)
- Gelişmiş İzleme Araçları Modülü: Modüler, genişletilebilir tasarım ile gelişmiş bellek takibi, metrik toplama ve esnek BE düğümü keşfi
- Sorgu Bilgi Araçları: Yapılandırılabilir içerik kısaltma, LLM ekleri için dosya dışa aktarma ve gelişmiş sorgu analitiği ile gelişmiş SQL açıklama ve profil oluşturma
- Kaynak Yöneticisi: Kaynak yönetimi ve meta veri sunumu (doris_mcp_server/tools/resources_manager.py)
- Bilgi İstemi Yöneticisi: Veri analizi için akıllı bilgi istemi şablonları (doris_mcp_server/tools/prompts_manager.py)
Gelişmiş Veritabanı Özellikleri:
- Sorgu Yürütme: Gelişmiş önbellekleme ve optimizasyon, gelişmiş bağlantı kararlılığı ve otomatik yeniden deneme mekanizmaları ile yüksek performanslı SQL yürütme (doris_mcp_server/utils/query_executor.py)
- Güvenlik Yönetimi: Yapılandırılabilir engellenen anahtar kelimeler, SQL enjeksiyon koruması, veri maskeleme ve birleşik güvenlik yapılandırma yönetimi ile kapsamlı SQL güvenlik doğrulaması (doris_mcp_server/utils/security.py)
- Meta Veri Çıkarma: Katalog federasyonu desteği ile kapsamlı veritabanı meta verileri (doris_mcp_server/utils/schema_extractor.py)
- Performans Analizi: Gelişmiş sütun analizi, performans izleme ve veri analizi araçları (doris_mcp_server/utils/analysis_tools.py)
Katalog Federasyonu Desteği: Çoklu katalog ortamları için tam destek (dahili Doris tabloları ve Hive, MySQL vb. harici veri kaynakları)
Kurumsal Güvenlik: Kimlik doğrulama, yetkilendirme, SQL enjeksiyon koruması ve ortam değişkeni yapılandırma desteği ile veri maskeleme yeteneklerine sahip kapsamlı güvenlik çerçevesi
Web Tabanlı Token Yönetimi: Veritabanı bağlama, gerçek zamanlı istatistikler ve kurumsal düzeyde erişim kontrolleri ile eksiksiz token yaşam döngüsü yönetimi için güvenli yalnızca localhost arayüzü (doris_mcp_server/auth/token_handlers.py)
Birleşik Yapılandırma Çerçevesi: Kapsamlı doğrulama, standartlaştırılmış parametre adlandırma ve information_schema'e otomatik geri dönüş ile akıllı varsayılan veritabanı işleme ile config.py aracılığıyla merkezi yapılandırma yönetimi

Sistem Gereksinimleri

Python: 3.12+
Veritabanı: Apache Doris bağlantı detayları (Ana Bilgisayar, Bağlantı Noktası, Kullanıcı, Parola, Veritabanı)

🚀 Hızlı Başlangıç

PyPI'den Kurulum

# Install the latest version
pip install doris-mcp-server

# Install specific version
pip install doris-mcp-server==0.6.0

💡 Komut Uyumluluğu: Kurulumdan sonra, geriye dönük uyumluluk için her iki doris-mcp-server komutu da kullanılabilir. Her iki komutu birbirinin yerine kullanabilirsiniz.

Akışkan HTTP Modunu Başlatma (Web Hizmeti)

Optimum performans ve güvenilirlik sunan birincil iletişim modu:

# Full configuration with database connection
doris-mcp-server \
    --transport http \
    --host 0.0.0.0 \
    --port 3000 \
    --db-host 127.0.0.1 \
    --db-port 9030 \
    --db-user root \
    --db-password your_password

Stdio Modunu Başlatma (Cursor ve diğer MCP istemcileri için)

MCP istemcileriyle doğrudan entegrasyon için standart giriş/çıkış modu:

# For direct integration with MCP clients like Cursor
doris-mcp-server --transport stdio

🌐 Token Yönetim Arayüzü (v0.6.0'da Yeni)

Kurumsal düzeyde token yönetimi için Web Tabanlı Token Yönetim Panosuna erişin:

Güvenli Erişim Gereksinimleri

Yalnızca Localhost Erişimi: Maksimum güvenlik için arayüz 127.0.0.1 ve ::1 ile sınırlıdır
Yönetici Kimlik Doğrulaması: Erişim için TOKEN_MANAGEMENT_ADMIN_TOKEN gerektirir

Yapılandırma Ön Koşulları:

# Required environment variables
ENABLE_HTTP_TOKEN_MANAGEMENT=true
ENABLE_TOKEN_AUTH=true
TOKEN_MANAGEMENT_ADMIN_TOKEN=your_secure_admin_token
TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

Arayüz Erişimi

# Access the token management interface
http://localhost:3000/token/management?admin_token=your_secure_admin_token

Mevcut İşlemler

📊 Token İstatistikleri: Aktif, süresi dolmuş ve toplam token'ların gerçek zamanlı özeti
➕ Token Oluşturma:
- Temel bilgiler (ID, açıklama, son kullanma)
- Veritabanı bağlama (ana bilgisayar, bağlantı noktası, kullanıcı, parola, veritabanı)
- Özel token değerleri veya otomatik oluşturulan güvenli token'lar
📋 Token Yönetimi:
- Veritabanı bağlama durumu ile tüm token'ları listeleme
- Tek tıklamayla token iptali
- Süresi dolmuş token'ların otomatik temizliği
🔒 Kurumsal Güvenlik:
- Tüm işlemler yönetici kimlik doğrulaması gerektirir
- Gerçek zamanlı IP doğrulaması
- Eksiksiz denetim günlüğü
- tokens.json dosyasına otomatik kalıcılık

🔐 Güvenlik Notu: Arayüz yalnızca localhost yönetimi için tasarlanmıştır. Uzaktan erişilemez, böylece token yönetim işlemleri için maksimum güvenlik sağlanır.

Kurulumu Doğrulama

# Check installation
doris-mcp-server --help

# Test HTTP mode (in another terminal)
curl http://localhost:3000/health

Ortam Değişkenleri (İsteğe Bağlı)

Komut satırı argümanları yerine ortam değişkenlerini kullanabilirsiniz:

# Basic Database Configuration
export DORIS_HOST="127.0.0.1"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

# Token Management Interface (Security-Critical)
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export ENABLE_TOKEN_AUTH=true
export TOKEN_MANAGEMENT_ADMIN_TOKEN="your_secure_admin_token"
export TOKEN_MANAGEMENT_ALLOWED_IPS="127.0.0.1,::1"

# Then start with simplified command
doris-mcp-server --transport http --host 0.0.0.0 --port 3000

Komut Satırı Argümanları

doris-mcp-server komutu aşağıdaki argümanları destekler:

Argüman	Açıklama	Varsayılan	Gerekli
`--transport`	Aktarım modu: `http` veya `stdio`	`http`	Hayır
`--host`	HTTP sunucu ana bilgisayarı (yalnızca HTTP modu)	`0.0.0.0`	Hayır
`--port`	HTTP sunucu bağlantı noktası (yalnızca HTTP modu)	`3000`	Hayır
`--db-host`	Doris veritabanı ana bilgisayarı	`localhost`	Hayır
`--db-port`	Doris veritabanı bağlantı noktası	`9030`	Hayır
`--db-user`	Doris veritabanı kullanıcı adı	`root`	Hayır
`--db-password`	Doris veritabanı parolası	-	Evet (ortamda değilse)

Geliştirme Kurulumu

Kaynaktan derlemek isteyen geliştiriciler için:

1. Depoyu Klonlayın

# Replace with the actual repository URL if different
git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

2. Bağımlılıkları Yükleyin

pip install -r requirements.txt

3. Ortam Değişkenlerini Yapılandırın

.env.example dosyasını .env olarak kopyalayın ve ayarları ortamınıza göre değiştirin:

cp .env.example .env

Anahtar Ortam Değişkenleri:

Veritabanı Bağlantısı:
- DORIS_HOST: Veritabanı ana bilgisayar adı (varsayılan: localhost)
- DORIS_PORT: Veritabanı bağlantı noktası (varsayılan: 9030)
- DORIS_USER: Veritabanı kullanıcı adı (varsayılan: root)
- DORIS_PASSWORD: Veritabanı parolası
- DORIS_DATABASE: Varsayılan veritabanı adı (varsayılan: information_schema)
- DORIS_MIN_CONNECTIONS: Minimum bağlantı havuzu boyutu (varsayılan: 5)
- DORIS_MAX_CONNECTIONS: Maksimum bağlantı havuzu boyutu (varsayılan: 20)
- DORIS_BE_HOSTS: İzleme için BE düğümleri (virgülle ayrılmış, isteğe bağlı - boşsa SHOW BACKENDS ile otomatik keşif)
- DORIS_BE_WEBSERVER_PORT: İzleme araçları için BE web sunucusu bağlantı noktası (varsayılan: 8040)
- FE_ARROW_FLIGHT_SQL_PORT: ADBC için Frontend Arrow Flight SQL bağlantı noktası (v0.5.0'da yeni)
- BE_ARROW_FLIGHT_SQL_PORT: ADBC için Backend Arrow Flight SQL bağlantı noktası (v0.5.0'da yeni)
Kimlik Doğrulama Yapılandırması (v0.6.0'da geliştirildi):
- ENABLE_TOKEN_AUTH: Belirteç tabanlı kimlik doğrulamayı etkinleştir (varsayılan: false)
- ENABLE_JWT_AUTH: JWT kimlik doğrulamasını etkinleştir (varsayılan: false)
- ENABLE_OAUTH_AUTH: OAuth kimlik doğrulamasını etkinleştir (varsayılan: false)
- ENABLE_DORIS_OAUTH_AUTH: Doris destekli OAuth kimlik doğrulamasını etkinleştir (varsayılan: false)
- DORIS_OAUTH_BASE_URL: Doris destekli OAuth keşif ve belirteç uç noktaları tarafından kullanılan genel temel URL
- TOKEN_FILE_PATH: Belirteç yönetimi için tokens.json dosyasının yolu (varsayılan: tokens.json)
- TOKEN_HOT_RELOAD: Belirteç yapılandırmasının anında yeniden yüklenmesini etkinleştir (varsayılan: true)
- DEFAULT_ADMIN_TOKEN: Varsayılan yönetici belirteci (ortam değişkeni ile özelleştirilebilir)
- DEFAULT_ANALYST_TOKEN: Varsayılan analist belirteci (ortam değişkeni ile özelleştirilebilir)
- DEFAULT_READONLY_TOKEN: Varsayılan salt okunur belirteç (ortam değişkeni ile özelleştirilebilir)
Eski Güvenlik Yapılandırması:
- AUTH_TYPE: Eski kimlik doğrulama türü (token/basic/oauth, kullanımdan kaldırıldı - bireysel anahtarları kullanın)
- TOKEN_SECRET: Eski belirteç gizli anahtarı (bunun yerine belirteç tabanlı kimlik doğrulama kullanın)
- ENABLE_SECURITY_CHECK: SQL güvenlik doğrulamasını etkinleştir/devre dışı bırak (varsayılan: true)
- BLOCKED_KEYWORDS: Engellenen SQL anahtar kelimelerinin virgülle ayrılmış listesi
- ENABLE_MASKING: Veri maskelemeyi etkinleştir (varsayılan: true)
- MAX_RESULT_ROWS: Maksimum sonuç satırı (varsayılan: 10000)
ADBC Yapılandırması (v0.5.0'da yeni):
- ADBC_DEFAULT_MAX_ROWS: ADBC sorguları için varsayılan maksimum satır (varsayılan: 100000)
- ADBC_DEFAULT_TIMEOUT: Saniye cinsinden varsayılan ADBC sorgu zaman aşımı (varsayılan: 60)
- ADBC_DEFAULT_RETURN_FORMAT: Varsayılan dönüş formatı - arrow/pandas/dict (varsayılan: arrow)
- ADBC_CONNECTION_TIMEOUT: Saniye cinsinden ADBC bağlantı zaman aşımı (varsayılan: 30)
- ADBC_ENABLED: ADBC araçlarını etkinleştir/devre dışı bırak (varsayılan: true)
Performans Yapılandırması:
- ENABLE_QUERY_CACHE: Sorgu önbelleğe almayı etkinleştir (varsayılan: true)
- CACHE_TTL: Saniye cinsinden önbellek yaşam süresi (varsayılan: 300)
- MAX_CONCURRENT_QUERIES: Maksimum eşzamanlı sorgu (varsayılan: 50)
- MAX_RESPONSE_CONTENT_SIZE: LLM uyumluluğu için maksimum yanıt içerik boyutu (varsayılan: 4096, v0.4.0'da yeni)
Gelişmiş Günlük Kaydı Yapılandırması (v0.5.0'da iyileştirildi):
- LOG_LEVEL: Günlük seviyesi (DEBUG/INFO/WARNING/ERROR, varsayılan: INFO)
- LOG_FILE_PATH: Günlük dosyası yolu (seviyeye göre otomatik olarak düzenlenir)
- ENABLE_AUDIT: Denetim günlüğünü etkinleştir (varsayılan: true)
- ENABLE_LOG_CLEANUP: Otomatik günlük temizlemeyi etkinleştir (varsayılan: true, v0.5.0'da geliştirildi)
- LOG_MAX_AGE_DAYS: Günlük dosyalarının gün cinsinden maksimum yaşı (varsayılan: 30, v0.5.0'da geliştirildi)
- LOG_CLEANUP_INTERVAL_HOURS: Saat cinsinden günlük temizleme kontrol aralığı (varsayılan: 24, v0.5.0'da geliştirildi)
- v0.5.0'daki Yeni Özellikler:
  - Seviye Tabanlı Dosya Ayırma: debug.log, info.log, warning.log, error.log, critical.log olarak otomatik ayırma
  - Zaman Damgalı Format: Milisaniye hassasiyeti ve düzgün hizalama ile geliştirilmiş biçimlendirme
  - Arka Plan Temizleme Zamanlayıcısı: Yapılandırılabilir saklama politikaları ile otomatik temizleme
  - Denetim İzi: Ayrı saklama yönetimi ile özel audit.log
  - Performans Optimizasyonu: Döndürme desteği ile minimum ek yük asenkron günlük kaydı

Kullanılabilir MCP Araçları

Aşağıdaki tablo, bir MCP istemcisi aracılığıyla çağrılmak üzere şu anda kullanılabilir olan ana araçları listeler:

Araç Adı	Açıklama	Parametreler
`exec_query`	SQL sorgusu çalıştır ve sonuçları döndür.	`sql` (string, Zorunlu), `db_name` (string, İsteğe bağlı), `catalog_name` (string, İsteğe bağlı), `max_rows` (integer, İsteğe bağlı), `timeout` (integer, İsteğe bağlı)
`get_table_schema`	Ayrıntılı tablo yapısı bilgisi al.	`table_name` (string, Zorunlu), `db_name` (string, İsteğe bağlı), `catalog_name` (string, İsteğe bağlı)
`get_db_table_list`	Belirtilen veritabanındaki tüm tablo adlarının listesini al.	`db_name` (string, İsteğe bağlı), `catalog_name` (string, İsteğe bağlı)
`get_db_list`	Tüm veritabanı adlarının listesini al.	`catalog_name` (string, İsteğe bağlı)
`get_table_comment`	Tablo yorum bilgisini al.	`table_name` (string, Zorunlu), `db_name` (string, İsteğe bağlı), `catalog_name` (string, İsteğe bağlı)
`get_table_column_comments`	Tablodaki tüm sütunlar için yorum bilgisini al.	`table_name` (string, Zorunlu), `db_name` (string, İsteğe bağlı), `catalog_name` (string, İsteğe bağlı)
`get_table_indexes`	Belirtilen tablo için indeks bilgisini al.	`table_name` (string, Zorunlu), `db_name` (string, İsteğe bağlı), `catalog_name` (string, İsteğe bağlı)
`get_recent_audit_logs`	Son döneme ait denetim günlüğü kayıtlarını al.	`days` (integer, İsteğe bağlı), `limit` (integer, İsteğe bağlı)
`get_catalog_list`	Tüm katalog adlarının listesini al.	`random_string` (string, Zorunlu)
`get_sql_explain`	LLM analizi için yapılandırılabilir içerik kısaltma ve dosya dışa aktarma ile SQL yürütme planı al.	`sql` (string, Zorunlu), `verbose` (boolean, İsteğe bağlı), `db_name` (string, İsteğe bağlı), `catalog_name` (string, İsteğe bağlı)
`get_sql_profile`	LLM optimizasyon iş akışları için içerik yönetimi ve dosya dışa aktarma ile SQL yürütme profili al.	`sql` (string, Zorunlu), `db_name` (string, İsteğe bağlı), `catalog_name` (string, İsteğe bağlı), `timeout` (integer, İsteğe bağlı)
`get_table_data_size`	FE HTTP API'si aracılığıyla tablo veri boyutu bilgisini al.	`db_name` (string, İsteğe bağlı), `table_name` (string, İsteğe bağlı), `single_replica` (boolean, İsteğe bağlı)
`get_monitoring_metrics_info`	Doris izleme metrik tanımlarını ve açıklamalarını al.	`role` (string, İsteğe bağlı), `monitor_type` (string, İsteğe bağlı), `priority` (string, İsteğe bağlı)
`get_monitoring_metrics_data`	Esnek BE keşfi ile düğümlerden gerçek Doris izleme metrik verilerini al.	`role` (string, İsteğe bağlı), `monitor_type` (string, İsteğe bağlı), `priority` (string, İsteğe bağlı)
`get_realtime_memory_stats`	Otomatik/manuel BE keşfi ile BE Bellek İzleyici aracılığıyla gerçek zamanlı bellek istatistiklerini al.	`tracker_type` (string, İsteğe bağlı), `include_details` (boolean, İsteğe bağlı)
`get_historical_memory_stats`	Esnek BE yapılandırması ile BE Bvar arayüzü aracılığıyla geçmiş bellek istatistiklerini al.	`tracker_names` (array, İsteğe bağlı), `time_range` (string, İsteğe bağlı)
`analyze_data_quality`	Bütünlük ve dağılım analizini birleştiren kapsamlı veri kalitesi analizi.	`table_name` (string, Zorunlu), `analysis_scope` (string, İsteğe bağlı), `sample_size` (integer, İsteğe bağlı), `business_rules` (array, İsteğe bağlı)
`trace_column_lineage`	SQL analizi ve bağımlılık eşleme yoluyla uçtan uca sütun köken takibi.	`target_columns` (array, Zorunlu), `analysis_depth` (integer, İsteğe bağlı), `include_transformations` (boolean, İsteğe bağlı)
`monitor_data_freshness`	Yapılandırılabilir güncellik eşikleri ile gerçek zamanlı veri bayatlığı izleme.	`table_names` (array, İsteğe bağlı), `freshness_threshold_hours` (integer, İsteğe bağlı), `include_update_patterns` (boolean, İsteğe bağlı)
`analyze_data_access_patterns`	Erişim deseni izleme ile kullanıcı davranış analizi ve güvenlik anomali tespiti.	`days` (integer, İsteğe bağlı), `include_system_users` (boolean, İsteğe bağlı), `min_query_threshold` (integer, İsteğe bağlı)
`analyze_data_flow_dependencies`	Tablolar ve görünümler arasında veri akışı etki analizi ve bağımlılık eşleme.	`target_table` (string, İsteğe bağlı), `analysis_depth` (integer, İsteğe bağlı), `include_views` (boolean, İsteğe bağlı)
`analyze_slow_queries_topn`	En yavaş N sorgu analizi ve desenleri ile performans darboğazı tespiti.	`days` (integer, İsteğe bağlı), `top_n` (integer, İsteğe bağlı), `min_execution_time_ms` (integer, İsteğe bağlı), `include_patterns` (boolean, İsteğe bağlı)
`analyze_resource_growth_curves`	Kaynak büyüme analizi ve eğilim tahmini ile kapasite planlaması.	`days` (integer, İsteğe bağlı), `resource_types` (array, İsteğe bağlı), `include_predictions` (boolean, İsteğe bağlı)
`exec_adbc_query`	ADBC (Arrow Flight SQL) protokolü kullanarak yüksek performanslı SQL yürütme.	`sql` (string, Zorunlu), `max_rows` (integer, İsteğe bağlı), `timeout` (integer, İsteğe bağlı), `return_format` (string, İsteğe bağlı)
`get_adbc_connection_info`	Arrow Flight SQL için ADBC bağlantı teşhisi ve durum izleme.	Parametre gerekmez

Not: Tüm meta veri araçları, çoklu katalog ortamları için katalog federasyonunu destekler. Gelişmiş izleme araçları, kapsamlı bellek takibi ve metrik toplama yetenekleri sağlar. v0.5.0'da yeni: Kurumsal veri yönetişimi için 7 gelişmiş analitik aracı ve büyük veri kümeleri için 3-10 kat performans iyileştirmesi sağlayan yüksek performanslı veri aktarımı için 2 ADBC aracı.

Doris destekli OAuth notu: Yukarıdaki tablo genel sunucu yeteneklerini açıklar. Doris destekli OAuth, işlem yüzeyi için yapılandırma kapılarını kullanır. MCP kaynakları, kaynak meta veri önbelleğe alma devre dışı bırakılmış olarak kullanılabilir. İncelenen meta veri araçları, DORIS_OAUTH_DB_TOOLS_ENABLED=true olduğunda çağrılabilir; exec_query ve get_sql_explain, Doris OAuth sorgu/açıklama kapıları etkinleştirildiğinde çağrılabilir. Bu MySQL kanalı işlemleri, oturum açmış Doris kullanıcı havuzu üzerinden çalışır, bu nedenle Doris RBAC nihai veri yetkilendirme arka ucudur. İstemler, ADBC, FE HTTP profili/izleme, denetim/yönetişim ve performans analitiği, kullanıcı başına yönlendirme veya açık bir hizmet hesabı/yönetici tasarımı olana kadar kapalı kalır.

4. Hizmeti Çalıştırma

Sunucuyu başlatmak için aşağıdaki komutu çalıştırın:

./start_server.sh

Bu komut, Akışkan HTTP MCP hizmeti ile FastAPI uygulamasını başlatır.

5. Docker üzerinde dağıtım

Docker'da yalnızca Doris MCP Sunucusunu çalıştırmak istiyorsanız:

cd doris-mcp-server
docker build -t doris-mcp-server .
docker run -d -p <port>:<port> -v /*your-host*/doris-mcp-server/.env:/app/.env --name <your-mcp-server-name> -it doris-mcp-server:latest

Hizmet Uç Noktaları:

Akışkan HTTP: http://<host>:<port>/mcp (Birincil MCP uç noktası - GET, POST, DELETE, OPTIONS'ı destekler)
Sağlık Kontrolü: http://<host>:<port>/health

Not: Sunucu, web tabanlı iletişim için Akışkan HTTP kullanır, birleşik istek/yanıt ve akış yetenekleri sağlar.

Kullanım

Doris MCP Sunucusu ile etkileşim bir MCP İstemcisi gerektirir. İstemci, sunucunun Akışkan HTTP uç noktasına bağlanır ve sunucunun araçlarını çağırmak için MCP spesifikasyonuna göre istekler gönderir.

Ana Etkileşim Akışı:

İstemci Başlatma: initialize (Akışkan HTTP) adresine bir /mcp yöntem çağrısı gönderin.
(İsteğe Bağlı) Araçları Keşfetme: İstemci, desteklenen araçların listesini, açıklamalarını ve parametre şemalarını almak için tools/list çağrısı yapabilir.
Araç Çağırma: İstemci, name ve arguments belirterek bir tools/call isteği gönderir.
- Örnek: Tablo Şemasını Al
  - name: get_table_schema
  - arguments: table_name, db_name, catalog_name dahil edin.
Yanıtı İşleme:
- Akışsız: İstemci, content veya isError içeren bir yanıt alır.
- Akışlı: İstemci, bir dizi ilerleme bildirimi ve ardından nihai bir yanıt alır.

Katalog Federasyonu Desteği

Doris MCP Sunucusu, birleşik bir arayüz içinde birden çok veri kataloğuyla (dahili Doris tabloları ve Hive, MySQL gibi harici veri kaynakları) etkileşime olanak tanıyan katalog federasyonunu destekler.

Temel Özellikler:

Çoklu Katalog Meta Veri Erişimi: Tüm meta veri araçları (get_db_list, get_db_table_list, get_table_schema, vb.), belirli katalogları sorgulamak için isteğe bağlı bir catalog_name parametresini destekler.
Kataloglar Arası SQL Sorguları: Üç parçalı tablo adlandırması kullanarak birden çok kataloğu kapsayan SQL sorguları yürütün.
Katalog Keşfi: Mevcut katalogları ve türlerini keşfetmek için get_catalog_list kullanın.

Üç Parçalı Adlandırma Gereksinimi:

Tüm SQL sorguları, tablo referansları için üç parçalı adlandırma kullanmak ZORUNDADIR:

Dahili Tablolar: internal.database_name.table_name
Harici Tablolar: catalog_name.database_name.table_name

Örnekler:

Mevcut Katalogları Al:

{
  "tool_name": "get_catalog_list",
  "arguments": {"random_string": "unique_id"}
}

Belirli Katalogdaki Veritabanlarını Al:

{
  "tool_name": "get_db_list", 
  "arguments": {"random_string": "unique_id", "catalog_name": "mysql"}
}

Dahili Kataloğu Sorgula:

{
  "tool_name": "exec_query",
  "arguments": {
    "random_string": "unique_id",
    "sql": "SELECT COUNT(*) FROM internal.ssb.customer"
  }
}

Harici Kataloğu Sorgula:

{
  "tool_name": "exec_query", 
  "arguments": {
    "random_string": "unique_id",
    "sql": "SELECT COUNT(*) FROM mysql.ssb.customer"
  }
}

Kataloglar Arası Sorgu:

{
  "tool_name": "exec_query",
  "arguments": {
    "random_string": "unique_id", 
    "sql": "SELECT i.c_name, m.external_data FROM internal.ssb.customer i JOIN mysql.test.user_info m ON i.c_custkey = m.customer_id"
  }
}

Güvenlik Yapılandırması

Doris MCP Sunucusu, v0.6.0'da geliştirilmiş gelişmiş kimlik doğrulama, yetkilendirme, SQL güvenlik doğrulaması ve veri maskeleme yeteneklerine sahip kapsamlı, kurumsal düzeyde bir güvenlik çerçevesi içerir.

Güvenlik Özellikleri (v0.6.0'da Geliştirildi)

🔐 Çoklu Kimlik Doğrulama Sistemi: Bağımsız kontrol anahtarlarına sahip eksiksiz Token, JWT ve OAuth kimlik doğrulaması
🔗 Token'a Bağlı Veritabanı Yapılandırması: Token'ların kendi veritabanı bağlantı parametrelerini taşımasına olanak tanıyan devrim niteliğinde yaklaşım
🔄 Anında Yeniden Yükleme Güvenliği: Akıllı token yeniden doğrulama ile sıfır kesinti süreli güvenlik yapılandırması güncellemeleri
⚡ Anında Doğrulama: Bağlantı anında gerçek zamanlı veritabanı ve kimlik doğrulama doğrulaması
🛡️ Rol Tabanlı Yetkilendirme: Dört kademeli güvenlik sınıflandırmasına sahip gelişmiş RBAC
🚫 Gelişmiş SQL Güvenliği: İyileştirilmiş desen algılama ile gelişmiş SQL enjeksiyon koruması
🎭 Akıllı Veri Maskeleme: Kullanıcı tabanlı izinlerle otomatik hassas veri maskeleme
📊 Güvenlik Analitiği: Kapsamlı denetim izleri ve güvenlik izleme

Kimlik Doğrulama Yapılandırması (v0.6.0)

Yeni kimlik doğrulama sistemini ayrıntılı kontrol ile yapılandırın:

# Individual Authentication Control (New in v0.6.0)
ENABLE_TOKEN_AUTH=true          # Enable token-based authentication
ENABLE_JWT_AUTH=false           # Enable JWT authentication  
ENABLE_OAUTH_AUTH=false         # Enable OAuth authentication

# Token Management (New in v0.6.0)
TOKEN_FILE_PATH=tokens.json     # Token configuration file
TOKEN_HOT_RELOAD=true          # Enable hot reloading

# Default Tokens (Customizable via environment)
DEFAULT_ADMIN_TOKEN=doris_admin_token_123456
DEFAULT_ANALYST_TOKEN=doris_analyst_token_123456
DEFAULT_READONLY_TOKEN=doris_readonly_token_123456

# Legacy Configuration (Deprecated)
# AUTH_TYPE=token               # Use individual switches instead
# TOKEN_SECRET=your_secret_key  # Use token-based auth instead

Doris Destekli OAuth Kimlik Doğrulaması

Doris destekli OAuth, Doris'in kendisinin yetkilendirme arka ucu olduğu ayrı bir OAuth modudur. MCP istemcisi bu sunucunun OAuth meta verilerini keşfeder, kullanıcı bir Doris kullanıcı adı ve parolasıyla oturum açar, sunucu kullanıcı başına bir Doris bağlantı havuzu oluşturarak bu kimlik bilgilerini doğrular ve verilen doa_ erişim token'ları, araç çağrılarını o Doris kullanıcısının havuzu üzerinden yönlendirir. MCP kapsamları hangi MCP işlemlerinin çağrılabileceğini kontrol eder; Doris RBAC, kullanıcının hangi katalogları, veritabanlarını, tabloları ve meta verileri görebileceğini kontrol eder.

Bu mod, harici OAuth/OIDC ile aynı değildir. ENABLE_DORIS_OAUTH_AUTH=true, ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true ve eski AUTH_TYPE=oauth ile çakışır; her iki mod da yapılandırılırsa başlatma hızlı bir şekilde başarısız olur. Standart bir MCP aracısı bir MCP URL'si girer ve bu URL için tam olarak bir OAuth davranışı keşfetmelidir, bu nedenle mevcut /auth/* harici OAuth oturum açma akışı, Doris destekli OAuth modunda kullanılmaz.

Minimal Yerel Yapılandırma

Aşağıdaki örnek, tek bir çalışan üzerinde yerel geliştirme içindir:

TRANSPORT=http
WORKERS=1

DORIS_HOST=localhost
DORIS_PORT=9030
DORIS_USER=root
DORIS_PASSWORD=<service-account-password>
DORIS_DATABASE=information_schema

ENABLE_DORIS_OAUTH_AUTH=true
DORIS_OAUTH_BASE_URL=http://localhost:3000
ENABLE_OAUTH_AUTH=false

DORIS_OAUTH_DB_TOOLS_ENABLED=true
DORIS_OAUTH_DB_TOOL_ALLOWLIST=get_db_list,get_db_table_list,get_table_schema,get_table_comment,get_table_column_comments,get_table_indexes,get_catalog_list
DORIS_OAUTH_QUERY_TOOLS_ENABLED=true
DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true

# Optional: let Doris RBAC, not the legacy MCP SQL guard, decide DDL/DML.
ENABLE_SECURITY_CHECK=false

Yapılandırılan hizmet Doris hesabı, başlatma doğrulaması ve Doris-OAuth dışı uyumluluk yolları tarafından hala gereklidir. Doris destekli OAuth istekleri, kullanıcı başına havuz eksikse başarısız-kapalıdır ve hizmet/küresel hesaba geri dönmemelidir.

Doris OAuth Araç Erişimi

DORIS_OAUTH_DB_TOOLS_ENABLED=true, incelenen meta veri kümesini açar. İncelenen araçlar şunlardır:

get_db_list
get_db_table_list
get_table_schema
get_table_comment
get_table_column_comments
get_table_indexes
get_catalog_list

Normal MCP OAuth akışları için, istemcilerin uzun bir --scopes listesi iletmesi gerekmez. OAuth isteği kapsamı atlarsa, sunucu yapılandırılan Doris OAuth yetenek zarfını verir. MySQL kanalı işlemleri için, oturum açmış Doris kullanıcısının gerçekten meta verileri okuyup okuyamayacağına, SQL çalıştırıp çalıştıramayacağına veya SQL'i açıklayıp açıklayamayacağına Doris RBAC karar verir.

DORIS_OAUTH_QUERY_TOOLS_ENABLED=true, exec_query açar. DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true, get_sql_explain açar. Eğer ENABLE_SECURITY_CHECK=true ise, eski MCP SQL güvenlik katmanı, Doris görmeden önce bazı SQL'leri yine de reddedebilir. Amaçlanan politika Doris RBAC'ın SQL/DDL/DML'ye karar vermesine izin vermek olduğunda ENABLE_SECURITY_CHECK=false olarak ayarlayın.

Doris destekli OAuth, bu aşamada, bu yollar kullanıcı başına kimlik bilgileri üzerinden ayrı ayrı yönlendirilmedikçe veya açık bir hizmet hesabı/yönetici tasarımı verilmedikçe, istemleri, ADBC'yi, FE HTTP profil/izlemeyi, denetim/yönetişimi veya performans analitiğini hala açmaz.

Mevcut Operasyonel Sınırlamalar

Doris destekli OAuth şu anda tek süreçli ve tek çalışanlıdır:

WORKERS=1 gereklidir. WORKERS=0, CPU sayısına genişler ve Doris destekli OAuth etkinleştirildiğinde başarısız olur.
OAuth istemcileri, yetkilendirme işlemleri, yetkilendirme kodları, erişim token'ları, yenileme token'ları ve DCR istemcileri yalnızca bellek içi ve süreç yereldir.
Kullanıcı başına Doris bağlantı havuzları süreç yereldir.
Süreç yeniden başlatma, kullanıcıların tekrar oturum açmasını gerektirir.
Token'lar ve havuzlar çalışanlar, süreçler veya düğümler arasında paylaşılmaz.
Durumsuz yatay ölçeklendirme ve çok düğümlü dağıtım, Doris destekli OAuth için henüz desteklenmemektedir.

Bir erişim token'ı başka bir şekilde geçerliyse ancak Doris kullanıcı havuzu yoksa, istek oturum açma gerekli / DORIS_OAUTH_POOL_MISSING ile başarısız olur. Sunucu, otomatik havuz yeniden oluşturma için ham Doris parolalarını saklamaz.

Üretim Sağlamlaştırması

Üretim dağıtımları için:

Geri döngü olmayan herhangi bir adres için bir HTTPS DORIS_OAUTH_BASE_URL kullanın.
DORIS_OAUTH_ALLOW_INSECURE_HTTP=false tutun; geri döngü olmayan http://, geliştirme için açıkça geçersiz kılınmadıkça reddedilir.
DORIS_OAUTH_TRUST_PROXY_HEADERS yalnızca kontrollü bir ters proxy arkasında etkinleştirin ve DORIS_OAUTH_TRUSTED_PROXY_CIDRS ayarlayın.
Oturum açma, yetkilendirme, token, yenileme, iptal ve DCR hız sınırlarını etkin tutun.
Nihai veri yetkilendirme sınırı olarak Doris RBAC'ı kullanın ve Doris kullanıcılarına yalnızca incelemeleri gereken verileri verin.
Doris parolalarını, yetkilendirme başlıklarını, erişim token'larını, yenileme token'larını, yetkilendirme kodlarını, PKCE doğrulayıcılarını veya istemci sırlarını günlüğe kaydetmeyin.
doa_ önekini Doris destekli OAuth erişim token'ları için ayrılmış olarak kabul edin; statik token'lar ve JWT taşıyıcı değerleri bunu kullanmamalıdır.
Dinamik İstemci Kaydını, geri döngü geliştirmesi için auto içinde tutun veya üretim DCR'yi ENABLE_DORIS_OAUTH_PRODUCTION_DCR=true ile açıkça yapılandırın.

Token'a Bağlı Veritabanı Yapılandırması (v0.6.0'da Yeni)

Veritabanı bağlama ile gelişmiş token yönetimi için bir tokens.json dosyası oluşturun:

{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "customer-a-token",
      "token": "customer_a_secure_token_12345",
      "description": "Customer A dedicated database access",
      "expires_hours": null,
      "is_active": true,
      "database_config": {
        "host": "customer-a-db.example.com",
        "port": 9030,
        "user": "customer_a_user",
        "password": "secure_password",
        "database": "customer_a_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    },
    {
      "token_id": "customer-b-token", 
      "token": "customer_b_secure_token_67890",
      "description": "Customer B dedicated database access",
      "expires_hours": 720,
      "is_active": true,
      "database_config": {
        "host": "customer-b-db.example.com",
        "port": 9030,
        "user": "customer_b_user", 
        "password": "secure_password",
        "database": "customer_b_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    }
  ]
}

Anında Yeniden Yükleme Yapılandırma Güncellemeleri (v0.6.0'da Yeni)

Sistem, yapılandırma değişikliklerini otomatik olarak algılar ve uygular:

Otomatik Algılama: Her 10 saniyede bir dosya değişikliği izleme
Anında Doğrulama: Yeni token'lar için anında veritabanı yapılandırması doğrulaması
Sıfır Kesinti Süresi: Hizmet kesintisi olmadan yapılandırma güncellemeleri
Geri Alma Koruması: Yapılandırma hatalarında otomatik geri alma
Denetim İzi: Yapılandırma değişikliklerinin eksiksiz günlüğe kaydedilmesi

Token Kimlik Doğrulama Örneği

# Client authentication with token
auth_info = {
    "type": "token",
    "token": "your_jwt_token",
    "session_id": "unique_session_id"
}

Temel Kimlik Doğrulama Örneği

# Client authentication with username/password
auth_info = {
    "type": "basic",
    "username": "analyst",
    "password": "secure_password",
    "session_id": "unique_session_id"
}

Yetkilendirme ve Güvenlik Seviyeleri

Sistem, hiyerarşik erişim kontrolüne sahip dört güvenlik seviyesini destekler:

Güvenlik Seviyesi	Erişim Kapsamı	Tipik Kullanım Durumları
Genel	Kısıtlamasız erişim	Genel raporlar, genel istatistikler
Dahili	Şirket çalışanları	Dahili panolar, iş metrikleri
Gizli	Yetkili personel	Müşteri verileri, mali raporlar
Özel	Üst düzey yönetim	Stratejik veriler, hassas analitikler

Rol Yapılandırması

Kullanıcı rollerini ve izinlerini yapılandırın:

# Example role configuration
role_permissions = {
    "data_analyst": {
        "security_level": "internal",
        "permissions": ["read_data", "execute_query"],
        "allowed_tables": ["sales", "products", "orders"]
    },
    "data_admin": {
        "security_level": "confidential", 
        "permissions": ["read_data", "execute_query", "admin"],
        "allowed_tables": ["*"]
    },
    "executive": {
        "security_level": "secret",
        "permissions": ["read_data", "execute_query", "admin"],
        "allowed_tables": ["*"]
    }
}

SQL Güvenlik Doğrulaması

Sistem, SQL sorgularını güvenlik risklerine karşı otomatik olarak doğrular:

Engellenen İşlemler

Ortam değişkenlerini kullanarak engellenen SQL işlemlerini yapılandırın (v0.4.2'de Yeni):

# Enable/disable SQL security check (New in v0.4.2)
ENABLE_SECURITY_CHECK=true

# Customize blocked keywords via environment variable (New in v0.4.2)
BLOCKED_KEYWORDS="DROP,DELETE,TRUNCATE,ALTER,CREATE,INSERT,UPDATE,GRANT,REVOKE,EXEC,EXECUTE,SHUTDOWN,KILL"

# Maximum query complexity score
MAX_QUERY_COMPLEXITY=100

Varsayılan Engellenen Anahtar Kelimeler (v0.4.2'de Birleştirildi):

DDL İşlemleri: DROP, CREATE, ALTER, TRUNCATE
DML İşlemleri: DELETE, INSERT, UPDATE
DCL İşlemleri: GRANT, REVOKE
Sistem İşlemleri: EXEC, EXECUTE, SHUTDOWN, KILL

SQL Enjeksiyon Koruması

Sistem otomatik olarak şunları algılar ve engeller:

Union tabanlı enjeksiyonlar: UNION SELECT saldırıları
Boolean tabanlı enjeksiyonlar: OR 1=1 desenleri
Zaman tabanlı enjeksiyonlar: SLEEP(), WAITFOR fonksiyonları
Yorum enjeksiyonları: --, /**/ desenleri
Yığılmış sorgular: ; ile ayrılmış birden çok ifade

Örnek Güvenlik Doğrulaması

# This query would be blocked
dangerous_sql = "SELECT * FROM users WHERE id = 1; DROP TABLE users;"

# This query would be allowed
safe_sql = "SELECT name, email FROM users WHERE department = 'sales'"

Veri Maskeleme Yapılandırması

Hassas bilgiler için otomatik veri maskelemeyi yapılandırın:

Yerleşik Maskeleme Kuralları

# Default masking rules
masking_rules = [
    {
        "column_pattern": r".*phone.*|.*mobile.*",
        "algorithm": "phone_mask",
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 3,
            "keep_suffix": 4
        },
        "security_level": "internal"
    },
    {
        "column_pattern": r".*email.*", 
        "algorithm": "email_mask",
        "parameters": {"mask_char": "*"},
        "security_level": "internal"
    },
    {
        "column_pattern": r".*id_card.*|.*identity.*",
        "algorithm": "id_mask", 
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 6,
            "keep_suffix": 4
        },
        "security_level": "confidential"
    }
]

Maskeleme Algoritmaları

Algoritma	Açıklama	Örnek
`phone_mask`	Telefon numaralarını maskeler	`138****5678`
`email_mask`	E-posta adreslerini maskeler	`j***n@example.com`
`id_mask`	Kimlik kartı numaralarını maskeler	`110101****1234`
`name_mask`	Kişisel isimleri maskeler	`张*明`
`partial_mask`	Oranla kısmi maskeleme	`abc***xyz`

Özel Maskeleme Kuralları

Yapılandırmanıza özel maskeleme kuralları ekleyin:

# Custom masking rule
custom_rule = {
    "column_pattern": r".*salary.*|.*income.*",
    "algorithm": "partial_mask",
    "parameters": {
        "mask_char": "*",
        "mask_ratio": 0.6
    },
    "security_level": "confidential"
}

Güvenlik Yapılandırması Örnekleri

Ortam Değişkenleri

# .env file
AUTH_TYPE=token
TOKEN_SECRET=your_jwt_secret_key
ENABLE_MASKING=true
MAX_RESULT_ROWS=10000
BLOCKED_SQL_OPERATIONS=DROP,DELETE,TRUNCATE,ALTER
MAX_QUERY_COMPLEXITY=100
ENABLE_AUDIT=true

Hassas Tablolar Yapılandırması

# Configure sensitive tables with security levels
sensitive_tables = {
    "user_profiles": "confidential",
    "payment_records": "secret", 
    "employee_salaries": "secret",
    "customer_data": "confidential",
    "public_reports": "public"
}

Güvenlik En İyi Uygulamaları

🔑 Güçlü Kimlik Doğrulama: Uygun sona erme süresine sahip JWT token'ları kullanın
🎯 En Az Ayrıcalık İlkesi: Gereken minimum izinleri verin
🔍 Düzenli Denetim: Güvenlik izleme için denetim günlüğünü etkinleştirin
🛡️ Girdi Doğrulaması: Tüm SQL sorguları otomatik olarak doğrulanır
🎭 Veri Sınıflandırması: Verileri güvenlik seviyeleriyle uygun şekilde sınıflandırın
🔄 Düzenli Güncellemeler: Güvenlik kurallarını ve yapılandırmalarını güncel tutun
Doris Destekli OAuth Sağlamlaştırması: HTTPS kullanın, bu modda harici OAuth'u devre dışı bırakın, WORKERS=1 tutun, MySQL kanalı veri erişimi için Doris RBAC'a güvenin ve yalnızca oturum açmış Doris kullanıcısının kimlik bilgilerini kullanacak şekilde yapılandırılmış ve doğrulanmış işlemleri sunun.

Güvenlik İzleme

Sistem kapsamlı güvenlik izleme sağlar:

# Security audit log example
{
    "timestamp": "2024-01-15T10:30:00Z",
    "user_id": "analyst_user",
    "action": "query_execution", 
    "resource": "customer_data",
    "result": "blocked",
    "reason": "insufficient_permissions",
    "risk_level": "medium"
}

⚠️ Önemli: Güvenlik yapılandırmalarını üretime dağıtmadan önce her zaman bir geliştirme ortamında test edin. Kuruluşunuzun gereksinimlerine göre güvenlik politikalarını düzenli olarak gözden geçirin ve güncelleyin.

Cursor ile Bağlanma

Cursor'ı bu MCP sunucusuna Stdio modunu (önerilir) veya Akışkan HTTP modunu kullanarak bağlayabilirsiniz.

Stdio Modu

Stdio modu, Cursor'ın sunucu sürecini doğrudan yönetmesine olanak tanır. Yapılandırma, Cursor'ın MCP Sunucu ayarları dosyası (genellikle ~/.cursor/mcp.json veya benzeri) içinde yapılır.

Yöntem 1: PyPI Kurulumunu Kullanma (Önerilir)

Paketi PyPI'den yükleyin ve Cursor'ı kullanacak şekilde yapılandırın:

pip install doris-mcp-server

Cursor'ı Yapılandırın: Cursor MCP yapılandırmanıza aşağıdakine benzer bir giriş ekleyin:

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Yöntem 2: uv Kullanma (Geliştirme)

uv kuruluysa ve kaynaktan çalıştırmak istiyorsanız:

uv run --project /path/to/doris-mcp-server doris-mcp-server

Not: /path/to/doris-mcp-server kısmını proje dizininizin gerçek mutlak yolu ile değiştirin.

Cursor'ı Yapılandırın: Cursor MCP yapılandırmanıza aşağıdakine benzer bir giriş ekleyin:

{
  "mcpServers": {
    "doris-stdio": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/your/doris-mcp-server", "doris-mcp-server"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Akışkan HTTP Modu

Akışkan HTTP modu, MCP sunucusunu önce bağımsız olarak çalıştırmanızı ve ardından Cursor'ı ona bağlanacak şekilde yapılandırmanızı gerektirir.

.env Yapılandırın: Veritabanı kimlik bilgilerinizin ve diğer gerekli ayarların proje dizinindeki .env dosyasında doğru şekilde yapılandırıldığından emin olun.
Sunucuyu Başlatın: Projenin kök dizininde terminalinizden sunucuyu çalıştırın:
```
./start_server.sh
```
Bu betik .env dosyasını okur ve Akışkan HTTP desteğiyle FastAPI sunucusunu başlatır. Sunucunun dinlediği ana bilgisayar ve bağlantı noktasını not edin (varsayılan 0.0.0.0:3000).
Cursor'ı Yapılandırın: Cursor MCP yapılandırmanıza, çalışan sunucunun Akışkan HTTP uç noktasını işaret eden aşağıdakine benzer bir giriş ekleyin:
```
{
  "mcpServers": {
    "doris-http": {
       "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```
Not: Sunucunuz farklı bir adreste çalışıyorsa ana bilgisayar/bağlantı noktasını ayarlayın. /mcp uç noktası birleşik Akışkan HTTP arayüzüdür.

Cursor'da her iki modu da yapılandırdıktan sonra, sunucuyu (örn. doris-stdio veya doris-http) seçebilir ve araçlarını kullanabilirsiniz.

Kiro ile Bağlanma

Veya Kiro MCP yapılandırma dosyanıza (genel için ~/.kiro/settings/mcp.json, proje kapsamlı için .kiro/settings/mcp.json) aşağıdakini ekleyin. Daha fazla ayrıntı için Kiro MCP belgelerine bakın.

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Dizin Yapısı

doris-mcp-server/
├── doris_mcp_server/           # Main server package
│   ├── main.py                 # Main entry point and FastAPI app
│   ├── multiworker_app.py      # Multi-worker application module (New in v0.6.0)
│   ├── auth/                   # Authentication modules (New in v0.6.0)
│   │   ├── token_manager.py    # Enterprise token management with hot reload
│   │   ├── jwt_manager.py      # JWT authentication provider
│   │   ├── oauth_provider.py   # OAuth authentication provider  
│   │   ├── oauth_handlers.py   # OAuth HTTP endpoint handlers
│   │   ├── token_handlers.py   # Token management HTTP endpoints
│   │   ├── auth_middleware.py  # Authentication middleware
│   │   └── __init__.py
│   ├── tools/                  # MCP tools implementation
│   │   ├── tools_manager.py    # Centralized tools management and registration
│   │   ├── resources_manager.py # Resource management and metadata exposure
│   │   ├── prompts_manager.py  # Intelligent prompt templates for data analysis
│   │   └── __init__.py
│   ├── utils/                  # Core utility modules
│   │   ├── config.py           # Configuration management with validation
│   │   ├── db.py               # Enhanced database connection management with token binding (Enhanced in v0.6.0)
│   │   ├── query_executor.py   # High-performance SQL execution with caching
│   │   ├── security.py         # Advanced security management and authentication (Enhanced in v0.6.0)
│   │   ├── schema_extractor.py # Metadata extraction with catalog federation
│   │   ├── analysis_tools.py   # Data analysis and performance monitoring
│   │   ├── data_governance_tools.py  # Data lineage and freshness monitoring (v0.5.0)
│   │   ├── data_quality_tools.py     # Comprehensive data quality analysis (v0.5.0)
│   │   ├── data_exploration_tools.py # Advanced statistical analysis (v0.5.0)
│   │   ├── security_analytics_tools.py # Access pattern analysis (v0.5.0)
│   │   ├── dependency_analysis_tools.py # Impact analysis and dependency mapping (v0.5.0)
│   │   ├── performance_analytics_tools.py # Query optimization and capacity planning (v0.5.0)
│   │   ├── adbc_query_tools.py       # High-performance Arrow Flight SQL operations (v0.5.0)
│   │   ├── logger.py           # Logging configuration
│   │   └── __init__.py
│   └── __init__.py
├── doris_mcp_client/           # MCP client implementation
│   ├── client.py               # Unified MCP client for testing and integration
│   ├── README.md               # Client documentation
│   └── __init__.py
├── logs/                       # Log files directory
├── tokens.json                 # Token configuration file (New in v0.6.0)
├── README.md                   # This documentation
├── RELEASE_NOTES_v0.6.0.md     # Release notes for v0.6.0
├── .env.example                # Environment variables template
├── requirements.txt            # Python dependencies
├── pyproject.toml              # Project configuration and entry points
├── uv.lock                     # UV package manager lock file
├── generate_requirements.py    # Requirements generation script
├── start_server.sh             # Server startup script
└── restart_server.sh           # Server restart script

Yeni Araçlar Geliştirme

Bu bölüm, merkezi araç yönetimi ile birleşik modüler mimariye dayalı olarak Doris MCP Sunucusuna yeni MCP araçları ekleme sürecini özetlemektedir.

1. Mevcut Yardımcı Modülleri Kullanın

Sunucu, yaygın veritabanı işlemleri için kapsamlı yardımcı modüller sağlar:

doris_mcp_server/utils/db.py: Bağlantı havuzu ve sağlık izleme ile veritabanı bağlantı yönetimi.
doris_mcp_server/utils/query_executor.py: Gelişmiş önbellekleme, optimizasyon ve performans izleme ile yüksek performanslı SQL yürütme.
doris_mcp_server/utils/schema_extractor.py: Tam katalog federasyonu desteği ile üst veri çıkarma.
doris_mcp_server/utils/security.py: Kapsamlı güvenlik yönetimi, SQL doğrulama ve veri maskeleme.
doris_mcp_server/utils/analysis_tools.py: Gelişmiş veri analizi ve istatistiksel araçlar.
doris_mcp_server/utils/config.py: Doğrulama ile yapılandırma yönetimi.
doris_mcp_server/utils/data_governance_tools.py: Veri kökeni takibi ve tazelik izleme (v0.5.0'da yeni).
doris_mcp_server/utils/data_quality_tools.py: Kapsamlı veri kalitesi analiz çerçevesi (v0.5.0'da yeni).
doris_mcp_server/utils/adbc_query_tools.py: Yüksek performanslı Arrow Flight SQL işlemleri (v0.5.0'da yeni).

2. Araç Mantığını Uygulayın

Yeni aracınızı doris_mcp_server/tools/tools_manager.py içindeki DorisToolsManager sınıfına ekleyin. Araç yöneticisi, birleşik arayüzlerle araç kaydı ve yürütmeye merkezi bir yaklaşım sağlar.

Örnek: Yeni bir analiz aracı ekleme:

# In doris_mcp_server/tools/tools_manager.py

async def your_new_analysis_tool(self, arguments: Dict[str, Any]) -> List[Dict[str, Any]]:
    """
    Your new analysis tool implementation
    
    Args:
        arguments: Tool arguments from MCP client
        
    Returns:
        List of MCP response messages
    """
    try:
        # Use existing utilities
        result = await self.query_executor.execute_sql_for_mcp(
            sql="SELECT COUNT(*) FROM your_table",
            max_rows=arguments.get("max_rows", 100)
        )
        
        return [{
            "type": "text",
            "text": json.dumps(result, ensure_ascii=False, indent=2)
        }]
        
    except Exception as e:
        logger.error(f"Tool execution failed: {str(e)}", exc_info=True)
        return [{
            "type": "text", 
            "text": f"Error: {str(e)}"
        }]

3. Aracı Kaydedin

Aracınızı aynı sınıftaki _register_tools metoduna ekleyin:

# In the _register_tools method of DorisToolsManager

@self.mcp.tool(
    name="your_new_analysis_tool",
    description="Description of your new analysis tool",
    inputSchema={
        "type": "object",
        "properties": {
            "parameter1": {
                "type": "string",
                "description": "Description of parameter1"
            },
            "parameter2": {
                "type": "integer", 
                "description": "Description of parameter2",
                "default": 100
            }
        },
        "required": ["parameter1"]
    }
)
async def your_new_analysis_tool_wrapper(arguments: Dict[str, Any]) -> List[Dict[str, Any]]:
    return await self.your_new_analysis_tool(arguments)

4. Gelişmiş Özellikler

Daha karmaşık araçlar için kapsamlı çerçeveden yararlanabilirsiniz:

Gelişmiş Önbellekleme: Gelişmiş performans için sorgu yürütücünün yerleşik önbelleklemesini kullanın
Kurumsal Güvenlik: Güvenlik yöneticisi aracılığıyla kapsamlı SQL doğrulama ve veri maskeleme uygulayın
Akıllı İstemler: Gelişmiş sorgu oluşturma için istem yöneticisini kullanın
Kaynak Yönetimi: Kaynak yöneticisi aracılığıyla üst verileri açığa çıkarın
Performans İzleme: İzleme yetenekleri için analiz araçlarıyla entegre edin

5. Test Etme

Dahil edilen MCP istemcisini kullanarak yeni aracınızı test edin:

# Using doris_mcp_client/client.py
from doris_mcp_client.client import DorisUnifiedMCPClient

async def test_new_tool():
    client = DorisUnifiedMCPClient()
    result = await client.call_tool("your_new_analysis_tool", {
        "parameter1": "test_value",
        "parameter2": 50
    })
    print(result)

MCP İstemcisi

Proje, test ve entegrasyon amaçları için birleşik bir MCP istemcisi (doris_mcp_client/) içerir. İstemci birden çok bağlantı modunu destekler ve MCP sunucusuyla etkileşim için uygun bir arayüz sağlar.

Ayrıntılı istemci belgeleri için doris_mcp_client/README.md sayfasına bakın.

Katkıda Bulunma

Sorunlar veya Çekme İstekleri aracılığıyla katkılar memnuniyetle karşılanır.

Lisans

Bu proje Apache 2.0 Lisansı altında lisanslanmıştır. Ayrıntılar için LICENSE dosyasına bakın.

SSS

S: Qwen3-32b ve diğer küçük parametreli modeller araçları çağırırken neden her zaman başarısız oluyor?

C: Bu yaygın bir sorundur. Ana neden, bu modellerin MCP araçlarını doğru kullanmak için daha açık yönlendirmeye ihtiyaç duymasıdır. Model için aşağıdaki talimat istemini eklemeniz önerilir:

Çince versiyonu：

<instruction>
尽可能使用MCP工具完成任务，仔细阅读每个工具的注解、方法名、参数说明等内容。请按照以下步骤操作：

1. 仔细分析用户的问题，从已有的Tools列表中匹配最合适的工具。
2. 确保工具名称、方法名和参数完全按照工具注释中的定义使用，不要自行创造工具名称或参数。
3. 传入参数时，严格遵循工具注释中规定的参数格式和要求。
4. 调用工具时，根据需要直接调用工具，但参数请求参考以下请求格式：{"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. 输出结果时，不要包含任何XML标签，仅返回纯文本内容。

<input>
用户问题：user_query
</input>

<output>
返回工具调用结果或最终答案，以及对结果的分析。
</output>
</instruction>

İngilizce versiyonu：

<instruction>
Use MCP tools to complete tasks as much as possible. Carefully read the annotations, method names, and parameter descriptions of each tool. Please follow these steps:

1. Carefully analyze the user's question and match the most appropriate tool from the existing Tools list.
2. Ensure tool names, method names, and parameters are used exactly as defined in the tool annotations. Do not create tool names or parameters on your own.
3. When passing parameters, strictly follow the parameter format and requirements specified in the tool annotations.
4. When calling tools, call them directly as needed, but refer to the following request format for parameters: {"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. When outputting results, do not include any XML tags, return plain text content only.

<input>
User question: user_query
</input>

<output>
Return tool call results or final answer, along with analysis of the results.
</output>
</instruction>

Döndürülen sonuçlar için başka gereksinimleriniz varsa, belirli gereksinimleri <output> etiketinde tanımlayabilirsiniz.

S: Farklı veritabanı bağlantıları nasıl yapılandırılır?

C: Veritabanı bağlantılarını birkaç şekilde yapılandırabilirsiniz:

Ortam Değişkenleri (Önerilir):

export DORIS_HOST="your_doris_host"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

Komut Satırı Argümanları:

doris-mcp-server --db-host your_host --db-port 9030 --db-user root --db-password your_password

Yapılandırma Dosyası: .env dosyasındaki ilgili yapılandırma öğelerini değiştirin.

S: İzleme araçları için BE düğümleri nasıl yapılandırılır?

C: Dağıtım senaryonuza göre uygun yapılandırmayı seçin:

Harici Ağ (Manuel Yapılandırma):

# Manually specify BE node addresses
DORIS_BE_HOSTS=10.1.1.100,10.1.1.101,10.1.1.102
DORIS_BE_WEBSERVER_PORT=8040

Dahili Ağ (Otomatik Keşif):

# Leave BE_HOSTS empty for auto-discovery
# DORIS_BE_HOSTS=  # Not set or empty
# System will use 'SHOW BACKENDS' command to get internal IPs

S: Optimizasyon için SQL Explain/Profile dosyaları LLM ile nasıl kullanılır?

C: Araçlar, LLM analizi için hem kısaltılmış içerik hem de tam dosyalar sağlar:

Analiz Sonuçlarını Alın:

{
  "content": "Truncated plan for immediate review",
  "file_path": "/tmp/explain_12345.txt",
  "is_content_truncated": true
}

LLM Analiz İş Akışı:
- Hızlı içgörüler için kısaltılmış içeriği inceleyin
- Tam dosyayı LLM'nize ek olarak yükleyin
- Optimizasyon önerileri veya performans analizi isteyin
- Önerilen iyileştirmeleri uygulayın

İçerik Boyutunu Yapılandırın:

MAX_RESPONSE_CONTENT_SIZE=4096  # Adjust as needed

S: Veri güvenliği ve maskeleme özellikleri nasıl etkinleştirilir?

C: .env dosyanızda aşağıdaki yapılandırmaları ayarlayın:

# Enable data masking
ENABLE_MASKING=true
# Set authentication type
AUTH_TYPE=token
# Configure token secret
TOKEN_SECRET=your_secret_key
# Set maximum result rows
MAX_RESULT_ROWS=10000

S: Stdio modu ile HTTP modu arasındaki fark nedir?

Stdio Modu: İstemcinin sunucu sürecini yönettiği MCP istemcileriyle (Cursor gibi) doğrudan entegrasyon için uygundur
HTTP Modu: Birden çok istemci bağlantısını destekleyen bağımsız web hizmeti, üretim ortamları için uygundur

Öneriler:

Geliştirme ve kişisel kullanım: Stdio modu
Üretim ve çok kullanıcılı ortamlar: HTTP modu

S: Bağlantı zaman aşımı sorunları nasıl çözülür?

C: Aşağıdaki çözümleri deneyin:

Zaman aşımı ayarlarını artırın:

# Set in .env file
QUERY_TIMEOUT=60
CONNECTION_TIMEOUT=30

Ağ bağlantısını kontrol edin:

# Test database connection
curl http://localhost:3000/health

Bağlantı havuzu yapılandırmasını optimize edin:
```
DORIS_MAX_CONNECTIONS=20
```

S: `at_eof` bağlantı hataları nasıl çözülür? (v0.5.0'da Tamamen Düzeltildi)

C: Sürüm 0.5.0, kapsamlı bağlantı havuzu yeniden tasarımı ile kritik at_eof bağlantı hatalarını tamamen çözmüştür:

Sorun:

at_eof hataları, bağlantı havuzu ön oluşturma ve uygunsuz bağlantı durumu yönetimi nedeniyle oluşuyordu
MySQL aiomysql okuyucu durumu bağlantı yaşam döngüsü sırasında tutarsız hale geliyordu
Eşzamanlı yük altında bağlantı havuzu kararsızlığı

Çözüm (v0.5.0):

Bağlantı Havuzu Stratejisi Revizyonu:
- Sıfır Minimum Bağlantı: Ön oluşturma sorunlarını önlemek için min_connections varsayılandan 0 olarak değiştirildi
- İsteğe Bağlı Bağlantı Oluşturma: Bağlantılar yalnızca gerektiğinde oluşturulur, eski bağlantı sorunlarını ortadan kaldırır
- Taze Bağlantı Stratejisi: Havuzdan her zaman taze bağlantılar alınır, oturum düzeyinde önbellekleme yok
Gelişmiş Sağlık İzleme:
- Zaman Aşımı Tabanlı Sağlık Kontrolleri: Bağlantı doğrulama sorguları için 3 saniyelik zaman aşımı
- Arka Plan Sağlık İzleyicisi: Her 30 saniyede bir sürekli havuz sağlığı izleme
- Proaktif Eskime Tespiti: Sorunlu bağlantıların otomatik tespiti ve temizlenmesi
Akıllı Kurtarma Sistemi:
- Otomatik Havuz Kurtarma: Kapsamlı hata işleme ile kendi kendini iyileştiren havuz
- Üstel Geri Çekilme Yeniden Deneme: 3 denemeye kadar akıllı yeniden deneme mekanizması
- Bağlantıya Özel Hata Tespiti: Bağlantıyla ilgili hataların hassas tanımlanması
Performans Optimizasyonları:
- Havuz Isınması: Optimum performans için akıllı bağlantı havuzu ısıtma
- Arka Plan Temizliği: Aktif işlemleri etkilemeden eski bağlantıların periyodik temizliği
- Bağlantı Teşhisi: Gerçek zamanlı bağlantı sağlığı izleme ve raporlama

Bağlantı Sağlığını İzleme:

# Monitor connection pool health in real-time
tail -f logs/doris_mcp_server_info.log | grep -E "(pool|connection|at_eof)"

# Check detailed connection diagnostics
tail -f logs/doris_mcp_server_debug.log | grep "connection health"

# View connection pool metrics
curl http://localhost:8000/health  # If running in HTTP mode

Optimum Bağlantı Performansı için Yapılandırma:

# Recommended connection pool settings in .env
DORIS_MAX_CONNECTIONS=20          # Adjust based on workload
CONNECTION_TIMEOUT=30             # Connection establishment timeout
QUERY_TIMEOUT=60                  # Query execution timeout

# Health monitoring settings
HEALTH_CHECK_INTERVAL=60          # Pool health check frequency

Sonuç: Önemli ölçüde iyileştirilmiş bağlantı kararlılığı ve performansı ile at_eof hatalarının %99,9 oranında ortadan kaldırılması.

S: MCP kütüphane sürüm uyumluluk sorunları nasıl çözülür? (v0.4.2'de Düzeltildi)

C: Sürüm 0.4.2, hem MCP 1.8.x hem de 1.9.x sürümlerini destekleyen akıllı bir MCP uyumluluk katmanı sunmuştur:

Sorun:

MCP 1.9.3, RequestContext sınıfında kırıcı değişiklikler getirdi (2'den 3 genel parametreye değiştirildi)
Bu, TypeError: Too few arguments for RequestContext hatalarına neden oldu

Çözüm (v0.4.2):

Akıllı Sürüm Tespiti: Yüklü MCP sürümünü otomatik olarak algılar
Uyumluluk Katmanı: Sürümler arasındaki API farklılıklarını zarifçe ele alır
Esnek Sürüm Desteği: Bağımlılıklarda mcp>=1.8.0,<2.0.0

Desteklenen MCP Sürümleri:

# Both versions now work seamlessly
pip install mcp==1.8.0  # Stable version (recommended)
pip install mcp==1.9.3  # Latest version with new features

Sürüm Bilgisi:

# Check which MCP version is being used
doris-mcp-server --transport stdio
# The server will log: "Using MCP version: x.x.x"

MCP ile ilgili başlatma hatalarıyla karşılaşırsanız:

# Recommended: Use stable version
pip uninstall mcp
pip install mcp==1.8.0

# Or upgrade to latest compatible version
pip install --upgrade doris-mcp-server==0.5.0

S: ADBC yüksek performans özellikleri nasıl etkinleştirilir? (v0.5.0'da yeni)

C: ADBC (Arrow Flight SQL), büyük veri kümeleri için 3-10 kat performans iyileştirmesi sağlar:

ADBC Bağımlılıkları (v0.5.0+ sürümünde otomatik olarak dahildir):

# ADBC dependencies are now included by default in doris-mcp-server>=0.5.0
# No separate installation required

Arrow Flight SQL Bağlantı Noktalarını Yapılandırın:

# Add to your .env file
FE_ARROW_FLIGHT_SQL_PORT=8096
BE_ARROW_FLIGHT_SQL_PORT=8097

İsteğe Bağlı ADBC Özelleştirmesi:

# Customize ADBC behavior (optional)
ADBC_DEFAULT_MAX_ROWS=200000
ADBC_DEFAULT_TIMEOUT=120
ADBC_DEFAULT_RETURN_FORMAT=pandas  # arrow/pandas/dict

ADBC Bağlantısını Test Edin:

# Use get_adbc_connection_info tool to verify setup
# Should show "status": "ready" and port connectivity

S: Yeni veri analitiği araçları nasıl kullanılır? (v0.5.0'da yeni)

C: 7 yeni analitik araç, kapsamlı veri yönetişim yetenekleri sağlar:

Veri Kalitesi Analizi:

{
  "tool_name": "analyze_data_quality",
  "arguments": {
    "table_name": "customer_data",
    "analysis_scope": "comprehensive",
    "sample_size": 100000
  }
}

Sütun Kökeni Takibi:

{
  "tool_name": "trace_column_lineage", 
  "arguments": {
    "target_columns": ["users.email", "orders.customer_id"],
    "analysis_depth": 3
  }
}

Veri Tazeliği İzleme:

{
  "tool_name": "monitor_data_freshness",
  "arguments": {
    "freshness_threshold_hours": 24,
    "include_update_patterns": true
  }
}

Performans Analitiği:

{
  "tool_name": "analyze_slow_queries_topn",
  "arguments": {
    "days": 7,
    "top_n": 20,
    "include_patterns": true
  }
}

S: Gelişmiş günlük kaydı sistemi nasıl kullanılır? (v0.5.0'da iyileştirildi)

C: Sürüm 0.5.0, otomatik yönetim ve seviye tabanlı organizasyon ile kapsamlı bir günlük kaydı sistemi sunar:

Günlük Dosyası Yapısı (v0.5.0'da yeni):

logs/
├── doris_mcp_server_debug.log      # DEBUG level messages
├── doris_mcp_server_info.log       # INFO level messages  
├── doris_mcp_server_warning.log    # WARNING level messages
├── doris_mcp_server_error.log      # ERROR level messages
├── doris_mcp_server_critical.log   # CRITICAL level messages
├── doris_mcp_server_all.log        # Combined log (all levels)
└── doris_mcp_server_audit.log      # Audit trail (separate)

Gelişmiş Günlük Kaydı Özellikleri:

Seviye Tabanlı Dosya Ayırma: Daha kolay sorun giderme için günlük seviyesine göre otomatik organizasyon
Zaman Damgalı Biçimlendirme: Profesyonel günlük kaydı için uygun hizalama ile milisaniye hassasiyeti
Otomatik Günlük Döndürme: Yapılandırılabilir dosya boyutu sınırları ile disk alanı sorunlarını önler
Arka Plan Temizliği: Yapılandırılabilir saklama politikaları ile akıllı temizlik zamanlayıcısı
Denetim İzi: Uyumluluk ve güvenlik izleme için ayrı denetim günlüğü

Günlükleri Görüntüleme:

# View real-time logs by level
tail -f logs/doris_mcp_server_info.log     # General operational info
tail -f logs/doris_mcp_server_error.log    # Error tracking
tail -f logs/doris_mcp_server_debug.log    # Detailed debugging

# View all activity in combined log
tail -f logs/doris_mcp_server_all.log

# Monitor specific operations
tail -f logs/doris_mcp_server_info.log | grep -E "(query|connection|tool)"

# View audit trail
tail -f logs/doris_mcp_server_audit.log

Yapılandırma:

# Enhanced logging configuration in .env
LOG_LEVEL=INFO                         # Base log level
ENABLE_AUDIT=true                      # Enable audit logging
ENABLE_LOG_CLEANUP=true                # Enable automatic cleanup
LOG_MAX_AGE_DAYS=30                    # Keep logs for 30 days
LOG_CLEANUP_INTERVAL_HOURS=24          # Check for cleanup daily

# Advanced settings
LOG_FILE_PATH=logs                     # Log directory (auto-organized)

Gelişmiş Günlüklerle Sorun Giderme:

# Debug connection issues
grep -E "(connection|pool|at_eof)" logs/doris_mcp_server_error.log

# Monitor tool performance
grep "execution_time" logs/doris_mcp_server_info.log

# Check system health
tail -20 logs/doris_mcp_server_warning.log

# View recent critical issues
cat logs/doris_mcp_server_critical.log

Günlük Temizleme Yönetimi:

Otomatik: Arka plan zamanlayıcısı LOG_MAX_AGE_DAYS değerinden daha eski dosyaları kaldırır
Manuel: Günlükler 10MB'a ulaştığında otomatik olarak döndürülür
Yedekleme: Her günlük seviyesi için 5 yedek dosya tutar
Performans: Sunucu performansı üzerinde minimum etki

S: Yeni Token-Bound Veritabanı Yapılandırması nasıl kullanılır? (v0.6.0'da yeni)

C: Devrim niteliğindeki token bağlı veritabanı yapılandırması, her token'ın güvenli çok kiracılı erişim için kendi veritabanı bağlantı parametrelerini taşımasına olanak tanır:

Token Kimlik Doğrulamasını Etkinleştir:

# In your .env file
ENABLE_TOKEN_AUTH=true
TOKEN_HOT_RELOAD=true
TOKEN_FILE_PATH=tokens.json

tokens.json Yapılandırmasını Oluştur:

{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "tenant-alpha",
      "token": "tenant_alpha_secure_token_123",
      "description": "Tenant Alpha database access",
      "expires_hours": null,
      "is_active": true,
      "database_config": {
        "host": "tenant-alpha-db.company.com",
        "port": 9030,
        "user": "alpha_user",
        "password": "secure_password",
        "database": "alpha_analytics",
        "charset": "UTF8"
      }
    }
  ]
}

Yapılandırma Önceliği (v0.6.0'da yeni):
- Token bağlı DB yapılandırması (en yüksek öncelik)
- Ortam değişkenleri (.env)
- Hiçbiri mevcut değilse hata
Canlı Yeniden Yükleme Avantajları:
- Servisi yeniden başlatmadan yeni kiracılar ekleme
- Veritabanı kimlik bilgilerini gerçek zamanlı güncelleme
- Hatalarda otomatik doğrulama ve geri alma
- Değişikliklerin eksiksiz denetim kaydı

Çok Kiracılı Kullanım:

# Different tokens access different databases automatically
curl -H "Authorization: Bearer tenant_alpha_secure_token_123" http://localhost:3000/mcp
curl -H "Authorization: Bearer tenant_beta_secure_token_456" http://localhost:3000/mcp

S: Doris destekli OAuth'un harici OAuth/OIDC'den farkı nedir?

C: Harici OAuth/OIDC, kimliği Google, Azure AD, GitHub, GitLab veya Keycloak gibi harici bir sağlayıcıya devreder. Doris destekli OAuth, kullanıcı Doris kimlik bilgileriyle oturum açtıktan sonra bu MCP sunucusu tarafından verilir. Sunucu, Doris kullanıcı adı/parolasını doğrular, kullanıcı başına bir Doris bağlantı havuzu oluşturur, doa_ erişim ve yenileme token'ları verir ve kullanıcının hangi verilere ve meta verilere erişebileceğine Doris RBAC'ın karar vermesini sağlar.

Bu modlar bir MCP URL'sinde birbirini dışlar. ENABLE_DORIS_OAUTH_AUTH=true ile ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true veya AUTH_TYPE=oauth'i birlikte etkinleştirmeyin; her iki OAuth modu da yapılandırılmışsa başlatma hızlıca başarısız olur.

Doris destekli OAuth şu anda MCP kaynaklarını devre dışı bırakılmış kaynaklar meta veri önbelleği ile sunar. DORIS_OAUTH_DB_TOOLS_ENABLED=true olduğunda incelenmiş meta veri araçlarını, DORIS_OAUTH_QUERY_TOOLS_ENABLED=true olduğunda exec_query'i ve DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true olduğunda SQL açıklamasını sunar. Normal istemcilerin uzun bir kapsam listesi iletmesi gerekmez; atlanan OAuth kapsamı, yapılandırılmış Doris OAuth yetenek zarfını verir. Bu MySQL kanalı işlemleri için nihai veri yetkilendirme arka ucu Doris RBAC olarak kalır.

S: Doris destekli OAuth birden fazla işçi veya birden fazla düğüm ile çalışabilir mi?

C: Mevcut uygulamada çalışamaz. Doris destekli OAuth, yalnızca bellek içi bir OAuth deposu ve süreç yerel kullanıcı başına Doris havuzları kullanır. Erişim token'ları, yenileme token'ları, yetkilendirme kodları, DCR istemcileri ve havuzlar işçiler, süreçler veya düğümler arasında paylaşılmaz.

Doris destekli OAuth ile WORKERS=1 kullanın. WORKERS=0 CPU sayısına genişler ve birden fazla etkin işçi oluşturacağı için başarısız olur. Durumsuz yatay ölçeklendirme, paylaşılan token depolama, paylaşılan şifreli Doris kimlik bilgileri, yapışkan oturum kurtarma ve havuz yeniden yapılandırması mevcut yetenekler değil, gelecekteki tasarımlardır.

S: Canlı Yeniden Yükleme nasıl çalışır ve güvenli midir? (v0.6.0'da yeni)

C: Canlı yeniden yükleme sistemi, kapsamlı güvenlik önlemleriyle kurumsal üretim ortamları için tasarlanmıştır:

Nasıl Çalışır:

Dosya İzleme: Değişiklikler için tokens.json dosyasını her 10 saniyede bir kontrol eder
Anında Doğrulama: Yeni token'lar veritabanı bağlantısı dahil olmak üzere doğrulanır
Atomik Güncellemeler: Ya hep ya hiç yapılandırma güncellemeleri
Geri Alma Koruması: Herhangi bir token doğrulaması başarısız olursa otomatik geri alma

Güvenlik Özellikleri:

Yedekleme ve Geri Yükleme: Değişikliklerden önce mevcut yapılandırma yedeklenir
Bağlantı Testi: Değişiklikler uygulanmadan önce veritabanı bağlantıları test edilir
Hata İzolasyonu: Geçersiz token'lar mevcut geçerli token'ları etkilemez
Denetim Günlüğü: Tüm yapılandırma değişikliklerinin eksiksiz kaydı

En İyi Uygulamalar:

# Monitor hot reload activity
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

# Test configuration before applying
cp tokens.json tokens.json.backup
# Make changes to tokens.json
# System will automatically validate and apply or rollback

S: Token yaşam döngüsü ve güvenliği nasıl yönetilir? (v0.6.0'da yeni)

C: Token yönetimi, kapsamlı güvenlik kontrollerine sahip isteğe bağlı yönetim uç noktalarıyla güvenli, dosya tabanlı bir yaklaşım kullanır.

Birincil Token Yönetim Yöntemi (Önerilen):

# 1. Edit tokens.json file directly (safest method)
nano tokens.json

# 2. Hot reload will automatically detect changes
# No server restart required - changes applied within 10 seconds

# 3. Monitor hot reload in logs
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

Yönetim Uç Noktaları (Güvenli, Yalnızca Yerel Erişim):

🛡️ GÜVENLİK: Bu uç noktalar kapsamlı güvenlik kontrolleriyle korunur ve varsayılan olarak devre dışıdır.

# Security Requirements (ALL must be met):
# ✓ HTTP token management explicitly enabled in configuration
# ✓ Access only from localhost (127.0.0.1/::1) - IP restrictions enforced
# ✓ Valid admin authentication token required
# ✓ Admin authentication enabled in configuration

# Enable HTTP token management (disabled by default)
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export TOKEN_MANAGEMENT_ADMIN_TOKEN=your_secure_admin_token
export REQUIRE_ADMIN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

# Access with proper authentication
curl -H "Authorization: Bearer your_secure_admin_token" http://127.0.0.1:3000/token/stats

# Demo page (local access only, with authentication)
# Access: http://127.0.0.1:3000/token/demo

Önerilen Token Yönetim İş Akışı:

Geliştirme/Test:

// tokens.json
{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "dev-token",
      "token": "dev_secure_token_123",
      "description": "Development environment access",
      "expires_hours": 24,
      "is_active": true
    }
  ]
}

Üretim Dağıtımı:

# Use secure token generation
openssl rand -hex 32  # Generate secure token

# Store in secure configuration management
# Never commit tokens to version control
# Use environment variables for sensitive tokens

Güvenlik Özellikleri:

Dosya Tabanlı Yönetim: Güvenli yapılandırma dosyaları aracılığıyla birincil yönetim
Canlı Yeniden Yükleme: Servis kesintisi olmadan otomatik yapılandırma güncellemeleri
Token Karması: Token'lar dahili olarak SHA-256 karmaları olarak saklanır
Denetim Kaydı: Tüm token işlemlerinin ve değişikliklerinin eksiksiz günlüğü
Sona Erme Yönetimi: Süresi dolmuş token'ların otomatik temizliği
Yalnızca Yerel Yönetici: Yönetim uç noktaları localhost erişimiyle sınırlıdır
Yapılandırma Doğrulaması: Token ve veritabanı yapılandırmalarının anında doğrulanması

Güvenlik En İyi Uygulamaları:

Token'ları her zaman güvenli yapılandırma dosyaları aracılığıyla yönetin
Token yönetim uç noktalarını asla harici ağlara maruz bırakmayın
Üretim için güçlü, rastgele oluşturulmuş token'lar kullanın
tokens.json için uygun dosya izinlerini uygulayın (600 veya 640)
Aktif token'ların ve kullanım modellerinin düzenli denetimi
Yetkisiz yapılandırma değişiklikleri için canlı yeniden yükleme günlüklerini izleyin

Diğer sorunlar için lütfen GitHub Sorunları'nı kontrol edin veya yeni bir sorun gönderin.