StarRocks

StarRocks Resmî MCP Sunucusu

StarRocks MCP Sunucusu, yapay zekâ asistanları ile StarRocks veritabanları arasında bir köprü görevi görür. Karmaşık istemci tarafı kurulumu gerektirmeden doğrudan SQL yürütme, veritabanı keşfi, grafikler aracılığıyla veri görselleştirme ve ayrıntılı şema/veri özetlerini alma imkânı sağlar.

Özellikler

• Doğrudan SQL Yürütme: SELECT sorgularını (read_query) ve DDL/DML komutlarını (write_query) çalıştırın.
• Veritabanı Keşfi: Veritabanlarını ve tabloları listeleyin, tablo şemalarını alın (starrocks:// kaynakları).
• Sistem Bilgileri: proc:// kaynak yolu üzerinden dahili StarRocks metriklerine ve durumlarına erişin.
• Ayrıntılı Özetler: Tabloların (table_overview) veya tüm veritabanlarının (db_overview) kapsamlı özetlerini alın; sütun tanımları, satır sayıları ve örnek veriler dahil.
• Veri Görselleştirme: Bir sorgu yürütün ve sonuçlardan doğrudan bir Plotly grafiği oluşturun (query_and_plotly_chart).
• Akıllı Önbellekleme: Tablo ve veritabanı özetleri, tekrarlanan istekleri hızlandırmak için bellekte önbelleğe alınır. Gerektiğinde önbellek atlanabilir.
• Esnek Yapılandırma: Bağlantı ayrıntılarını ve davranışı ortam değişkenleri aracılığıyla ayarlayın.

Ön Koşullar

• Python 3.11 veya daha yeni bir sürüm.
• Erişilebilir bir StarRocks kümesi (FE hizmeti). Varsayılan olarak sunucu, MySQL protokolü üzerinden localhost:9030 adresine bağlanır.
• uv — Astral'dan hızlı bir Python paketi ve proje yöneticisi (pip + virtualenv için modern bir alternatif). Bu proje, bağımlılıkları çözmek, sanal ortamı oluşturmak ve sunucuyu başlatmak için uv kullanır. Bu README boyunca yer alan uv run komutları, ilk kullanımda otomatik olarak izole bir ortam oluşturur ve gerekli bağımlılıkları kurar; bu nedenle manuel bir pip install adımı gerekmez.

uv Kurulumu

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via Homebrew / pipx / pip
brew install uv
# pipx install uv
# pip install uv

Diğer seçenekler için resmî uv kurulum kılavuzuna bakın. Kurulumdan sonra, PATH üzerinde olduğunu doğrulayın:

uv --version

Kurulum

Genellikle paketi manuel olarak kurmanız gerekmez — MCP ana bilgisayarı, paketi sizin için uv aracılığıyla başlatır (aşağıdaki Yapılandırma bölümüne bakın). uv, paketi ve bağımlılıklarını ihtiyaç duyulduğunda getirir.

Test veya geliştirme için doğrudan çalıştırmak üzere:

# Run the published package in a throwaway environment
uv run --with mcp-server-starrocks mcp-server-starrocks --help

# Or, from a local checkout of this repository
git clone https://github.com/starrocks/mcp-server-starrocks.git
cd mcp-server-starrocks
uv sync                      # create the virtual environment and install dependencies
uv run mcp-server-starrocks --help

Yapılandırma

MCP sunucusu genellikle bir MCP ana bilgisayarı aracılığıyla çalıştırılır. Yapılandırma, StarRocks MCP sunucusu sürecinin nasıl başlatılacağını belirterek ana bilgisayara iletilir.

Streamable HTTP Kullanımı (önerilir):

Sunucuyu Streamable HTTP modunda başlatmak için:

Önce StarRocks bağlantısının çalıştığını test edin (9030, HTTP sunucu bağlantı noktası değil, StarRocks MySQL protokol bağlantı noktasıdır):

$ STARROCKS_URL=root:@localhost:9030 uv run mcp-server-starrocks --test

Sunucuyu başlatın:

uv run mcp-server-starrocks --mode streamable-http --port 8000

Ardından MCP'yi şu şekilde yapılandırın:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Docker Kullanımı:

Görüntüyü derleyin:

docker build -t mcp-server-starrocks:local .

Sürümlü bir görüntü derleyin ve gönderin:

docker build -t <registry>/<namespace>/mcp-starrocks:0.4.0 .
docker push <registry>/<namespace>/mcp-starrocks:0.4.0

Sunucuyu Streamable HTTP modunda başlatın:

docker run --rm -p 8000:8000 \
  -e STARROCKS_HOST=host.docker.internal \
  -e STARROCKS_PORT=9030 \
  -e STARROCKS_USER=root \
  -e STARROCKS_PASSWORD='' \
  mcp-server-starrocks:local

Ardından MCP istemcisini şu şekilde yapılandırın:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Kurulu paketle uv Kullanımı (bireysel ortam değişkenleri):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

Kurulu paketle uv Kullanımı (bağlantı URL'si):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

Yerel dizinle uv Kullanımı (geliştirme için):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

Yerel dizin ve bağlantı URL'si ile uv Kullanımı:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

Komut Satırı Bağımsız Değişkenleri:

Sunucu aşağıdaki komut satırı bağımsız değişkenlerini destekler:

uv run mcp-server-starrocks --help

• --mode {stdio,sse,http,streamable-http}: Aktarım modu (varsayılan: stdio veya MCP_TRANSPORT_MODE ortam değişkeni)
• --host HOST: HTTP modları için sunucu ana bilgisayarı (varsayılan: localhost)
• --port PORT: HTTP modları için sunucu bağlantı noktası
• --test: İşlevselliği doğrulamak için test modunda çalıştırın

Örnekler:

# Start in streamable HTTP mode on custom host/port
uv run mcp-server-starrocks --mode streamable-http --host 0.0.0.0 --port 8080

# Start in stdio mode (default)
uv run mcp-server-starrocks --mode stdio

# Run test mode
uv run mcp-server-starrocks --test

• url alanı, MCP sunucunuzun Streamable HTTP uç noktasını göstermelidir (ana bilgisayarı/bağlantı noktasını gerektiği gibi ayarlayın).
• Bu yapılandırmayla istemciler, HTTP POST istekleri üzerinden standart JSON kullanarak sunucuyla etkileşim kurabilir. Özel bir SDK gerekmez.
• Tüm araç API'leri, yukarıda açıklandığı gibi standart JSON kabul eder ve döndürür.

Not: sse (Sunucu Tarafından Gönderilen Etkinlikler) modu kullanımdan kaldırılmıştır ve artık bakımı yapılmamaktadır. Tüm yeni entegrasyonlar için lütfen Streamable HTTP modunu kullanın.

Ortam Değişkenleri:

Bağlantı Yapılandırması

StarRocks bağlantısını, bireysel ortam değişkenlerini veya tek bir bağlantı URL'sini kullanarak yapılandırabilirsiniz:

Seçenek 1: Bireysel Ortam Değişkenleri

• STARROCKS_HOST: (İsteğe bağlı) StarRocks FE hizmetinin ana bilgisayar adı veya IP adresi. Varsayılan localhost değeridir.
• STARROCKS_PORT: (İsteğe bağlı) StarRocks FE hizmetinin MySQL protokol bağlantı noktası. Varsayılan 9030 değeridir.
• STARROCKS_USER: (İsteğe bağlı) StarRocks kullanıcı adı. Varsayılan root değeridir.
• STARROCKS_PASSWORD: (İsteğe bağlı) StarRocks parolası. Varsayılan boş dizedir.
• STARROCKS_PASSWORD_FILE: (İsteğe bağlı) Parolayı içeren UTF-8 metin dosyasının yolu. Bu, systemd kimlik bilgileri gibi dosya tabanlı gizli enjeksiyonda kullanışlıdır. Sondaki bir satır sonu yok sayılır. Bu yalnızca STARROCKS_PASSWORD veya STARROCKS_URL aracılığıyla açık bir parola sağlanmadığında kullanılır.
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (İsteğe bağlı, yalnızca macOS) Parolayı Keychain'den okurken kullanılacak genel parola hizmet adı. Bu yalnızca açık bir parola veya STARROCKS_PASSWORD_FILE yapılandırılmadığında kullanılır.
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (İsteğe bağlı, yalnızca macOS) Parolayı Keychain'den okurken kullanılacak genel parola hesap adı. Varsayılan, çözümlenen StarRocks kullanıcısıdır.
• STARROCKS_DB: (İsteğe bağlı) Araç bağımsız değişkenlerinde veya kaynak URI'lerinde belirtilmezse kullanılacak varsayılan veritabanı. Ayarlanırsa, bağlantı bu veritabanını USE yapmayı dener. table_overview ve db_overview gibi araçlar, bağımsız değişkenlerinde veritabanı kısmı atlanırsa bunu kullanır. Varsayılan boştur (varsayılan veritabanı yok).
• STARROCKS_QUERY_TIMEOUT: (İsteğe bağlı) Bir sorgunun sonuçlarının beklenmesi için vazgeçmeden önce beklenecek saniye sayısı (tam sayı olarak). Varsayılan olarak ayarlanmamıştır; bu, önceki davranışla eşleşerek süresiz bekler. Takılı kalan veya uzun süren bir sorgunun bir araç çağrısını sonsuza dek engellemek yerine başarısız olması gerekiyorsa bunu ayarlayın.

Seçenek 2: Bağlantı URL'si (bireysel değişkenlere göre önceliklidir)

• STARROCKS_URL: (İsteğe bağlı) Tüm bağlantı parametrelerini tek bir değişkende içeren bir bağlantı URL'si dizesi. Biçim: [<schema>://]user:password@host:port/database. Şema kısmı isteğe bağlıdır. Bu değişken ayarlandığında, bireysel STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD ve STARROCKS_DB değişkenlerine göre öncelik kazanır.

  Örnekler:

  • root:mypass@localhost:9030/test_db
  • mysql://admin:secret@db.example.com:9030/production
  • starrocks://user:pass@192.168.1.100:9030/analytics

Parola önceliği:

• STARROCKS_URL içine gömülü bir parola kazanır; user:@host:9030/db gibi açık bir boş parola dahil.
• STARROCKS_URL parolayı atlarsa, ayarlandığında STARROCKS_PASSWORD kullanılır.
• Açık parola kaynağı ayarlanmamışsa ve STARROCKS_PASSWORD_FILE yapılandırılmışsa, parola bu dosyadan okunur.
• Açık parola veya parola dosyası yapılandırılmamışsa ve STARROCKS_PASSWORD_KEYCHAIN_SERVICE ayarlanmışsa, parola macOS Keychain'den okunur.

macOS Keychain örneği

Parolayı saklayın:

security add-generic-password -U -a root -s mcp-server-starrocks -w 'secret'

Saklanan parolayı doğrulayın:

security find-generic-password -a root -s mcp-server-starrocks -w

Bu sunucuyla kullanın:

export STARROCKS_URL=root@localhost:9030/test_db
export STARROCKS_PASSWORD_KEYCHAIN_SERVICE=mcp-server-starrocks
export STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT=root

systemd şifreli kimlik bilgileri örneği (systemd 250 veya sonrası)

Sunucu, systemd-creds öğesini kendisi çağırmaz. Dağıtım zamanında bir yönetici parolayı şifreler; hizmet başlangıcında systemd, parolayı hizmetin kimlik bilgileri dizinine çözer ve bu sunucuya yalnızca dosya yolunu gösterir.

Parolayı kabuk geçmişine koymadan ana bilgisayara bağlı şifreli bir kimlik bilgisi oluşturun:

sudo -v
sudo install -d -m 0700 /etc/credstore.encrypted
sudo systemd-ask-password -n "StarRocks password:" \
  | sudo systemd-creds encrypt \
      --name=starrocks-password \
      - /etc/credstore.encrypted/starrocks-password.cred

Kimlik bilgisini hizmet birimine ekleyin. %d belirteci, hizmete özgü kimlik bilgileri dizinine genişler:

[Service]
LoadCredentialEncrypted=starrocks-password:/etc/credstore.encrypted/starrocks-password.cred
Environment=STARROCKS_PASSWORD_FILE=%d/starrocks-password
PrivateMounts=yes

STARROCKS_PASSWORD değerini ayarlanmamış tutun ve parolayı STARROCKS_URL içinden çıkarın, ardından birimi yeniden yükleyin ve hizmeti yeniden başlatın. Şifreli kimlik bilgisi normalde yerel ana bilgisayara (ve mevcut olduğunda TPM2 aygıtına) bağlıdır; yalnızca hizmet etkinleştirilirken çözülür. Hizmet süreci ve kök ayrıcalıklarına sahip yöneticiler, çalışma zamanında düz metin parolaya yine de erişebilir. Gizlilik sağlamayan systemd-creds encrypt --with-key=null kullanmayın.

Ek Yapılandırma

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (İsteğe bağlı) StarRocks FE hizmetinin Arrow Flight SQL bağlantı noktası. Ayarlanırsa, sunucu standart MySQL protokolü yerine yüksek performanslı Arrow Flight SQL protokolünü (ADBC sürücüleri aracılığıyla) kullanarak bağlanır. Varsayılan MySQL bağlantısını kullanmak için ayarlanmamış bırakın. Ana bilgisayar, kullanıcı ve parola, yukarıda açıklanan aynı bağlantı ayarlarından alınır.

• STARROCKS_OVERVIEW_LIMIT: (İsteğe bağlı) Önbelleği doldurmak için veri getirilirken özet araçlarının (table_overview, db_overview) ürettiği toplam metin için yaklaşık bir karakter sınırı. Bu, çok büyük şemalar veya çok sayıda tablo için aşırı bellek kullanımını önlemeye yardımcı olur. Varsayılan 20000 değeridir.

• STARROCKS_MCP_OUTPUT_DIR: (İsteğe bağlı) read_query aracının output_file bağımsız değişkeni göreli bir yol olduğunda kullandığı dizin. Varsayılan ~/.mcp-server-starrocks/output/ değeridir. Dizin ihtiyaç duyulduğunda oluşturulur. output_file öğesine iletilen mutlak yollar (~ önekli yollar dahil) bu ayarı atlar. Not: dosyalar, MCP sunucusunun çalıştığı makineye yazılır. Claude Code / Claude Desktop için sunucu yerel olarak çalışır, bu nedenle dosyalar dizüstü bilgisayarınıza kaydedilir. Uzak/http dağıtımları için dosya, istemciye değil sunucuya kaydedilir.

• STARROCKS_CHART_OUTPUT_DIR: (İsteğe bağlı) query_and_plotly_chart aracının etkileşimli HTML grafiklerini yazdığı dizin (format="html" olduğunda). Varsayılan, sistem geçici dizinidir. Dizin ihtiyaç duyulduğunda oluşturulur. Not: diğer çıktı dosyaları gibi, grafikler de MCP sunucusunun çalıştığı makineye yazılır.

• STARROCKS_CHART_INCLUDE_PLOTLYJS: (İsteğe bağlı) plotly.js öğesinin HTML grafiklerine nasıl paketlendiğini kontrol eder. cdn (varsayılan) dosyaları küçük tutar ancak görüntülerken ağ erişimi gerektirir; inline/true çevrimdışı kullanım için tam kitaplığı gömer; directory ve false de kabul edilir (Plotly'nin write_html öğesine iletilir).

• STARROCKS_CHART_DEFAULT_FORMAT: (İsteğe bağlı) format bağımsız değişkeni atlandığında query_and_plotly_chart için varsayılan çıktı biçimi. json, png, jpeg (varsayılan) veya html değerlerinden biri. Her çağrıda format iletmeden her zaman STARROCKS_CHART_OUTPUT_DIR konumuna etkileşimli bir grafik dosyası (satır içi PNG önizlemesiyle) yazmak için html olarak ayarlayın. Geçersiz değerler, bir uyarıyla jpeg değerine geri döner.

• STARROCKS_MYSQL_AUTH_PLUGIN: (İsteğe bağlı) StarRocks FE hizmetine bağlanırken kullanılacak kimlik doğrulama eklentisini belirtir. Örneğin, StarRocks dağıtımınız düz metin parola kimlik doğrulaması gerektiriyorsa (belirli LDAP veya harici kimlik doğrulama kurulumları kullanılırken olduğu gibi) mysql_clear_password olarak ayarlayın. Bunu yalnızca ortamınız özel olarak gerektiriyorsa ayarlayın; aksi takdirde varsayılan auth_plugin kullanılır.

TLS / SSL Yapılandırması

Bu değişkenler bağlantı için TLS'yi kontrol eder. Hiçbiri ayarlanmadığında, temel mysql.connector varsayılan davranışını korur (ssl-mode=PREFERRED): sunucu TLS'yi destekliyorsa bağlantı şifrelenir, ancak sunucu sertifikası doğrulanmaz. Gerçek güvenlik için bir CA sertifikası sağlayın ve doğrulamayı etkinleştirin.

• STARROCKS_SSL_DISABLED: (İsteğe bağlı) TLS'i zorla devre dışı bırakmak için true olarak ayarlayın. Diğer tüm SSL ayarlarını geçersiz kılar. Varsayılan false değerindedir.
• STARROCKS_SSL_CA: (İsteğe bağlı) StarRocks sunucu sertifikasını doğrulamak için kullanılan CA sertifikasının (PEM) yolu.
• STARROCKS_SSL_CERT: (İsteğe bağlı) Karşılıklı TLS (mTLS) için istemci sertifikasının (PEM) yolu.
• STARROCKS_SSL_KEY: (İsteğe bağlı) Karşılıklı TLS (mTLS) için istemci özel anahtarının (PEM) yolu.
• STARROCKS_SSL_VERIFY_CERT: (İsteğe bağlı) Sunucu sertifikasını CA'ya karşı doğrulamak için true olarak ayarlayın. Varsayılan false değerindedir.
• STARROCKS_SSL_VERIFY_IDENTITY: (İsteğe bağlı) Sunucu ana bilgisayar adının sertifikayla eşleştiğini de doğrulamak için true olarak ayarlayın. Varsayılan false değerindedir.
• STARROCKS_TLS_VERSIONS: (İsteğe bağlı) İzin verilen TLS sürümlerinin virgülle ayrılmış listesi, örn. TLSv1.2,TLSv1.3.

Örnek (sunucuyu bir CA sertifikasına karşı doğrulayın):

"env": {
  "STARROCKS_HOST": "your-fe-host",
  "STARROCKS_PORT": "9030",
  "STARROCKS_USER": "root",
  "STARROCKS_PASSWORD": "your-password",
  "STARROCKS_SSL_CA": "/path/to/ca.pem",
  "STARROCKS_SSL_VERIFY_CERT": "true",
  "STARROCKS_SSL_VERIFY_IDENTITY": "true"
}

Yüksek performanslı Arrow Flight SQL bağlantısı için (STARROCKS_FE_ARROW_FLIGHT_SQL_PORT ile etkinleştirilir), TLS ayrıca kontrol edilir:

• STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS: (İsteğe bağlı) Düz metin grpc:// yerine grpc+tls:// kullanmak için true olarak ayarlayın. Etkinleştirildiğinde, STARROCKS_SSL_CA TLS kök sertifikası olarak kullanılır ve STARROCKS_SSL_VERIFY_CERT=false (varsayılan) sunucu sertifikası doğrulamasını atlar.

Güvenlik notu: düz metin parolaları doğrudan mcp.json içinde saklamaktan kaçının. STARROCKS_PASSWORD (ve sertifika yollarını) bir sır yöneticisinden veya ortamdan enjekte etmeyi tercih edin ve kimlik bilgilerini asla sürüm kontrolüne kaydetmeyin.

• MCP_TRANSPORT_MODE: (İsteğe bağlı) MCP Sunucusunun hizmetlerini nasıl sunduğunu belirten iletişim modu. Kullanılabilir seçenekler:
  • stdio (varsayılan): Standart giriş/çıkış üzerinden iletişim kurar, MCP Ana Bilgisayar barındırması için uygundur.
  • streamable-http (Akışkan HTTP): RESTful API çağrılarını destekleyen bir Akışkan HTTP Sunucusu olarak başlar.
  • sse: (Kullanımdan kaldırıldı, önerilmez) Sunucu Tarafından Gönderilen Olaylar (SSE) akış modunda başlar, akış yanıtları gerektiren senaryolar için uygundur. Not: SSE modu artık bakımı yapılmamaktadır, tek tip olarak Akışkan HTTP modunun kullanılması önerilir.

Bileşenler

Araçlar

• read_query

  • Açıklama: Bir SELECT sorgusu veya ResultSet döndüren diğer komutları çalıştırın (örn. SHOW, DESCRIBE). İsteğe bağlı olarak, tam sonucu satır içi döndürmek yerine yerel bir dosyaya yazın — model bağlamına sığmayacak kadar büyük sonuçlar için kullanışlıdır.
  • Girdi:

    {
      "query": "SQL query string",
      "db": "database name (optional, uses default database if not specified)",
      "output_file": "optional path; if set, writes the full result to disk and returns only a summary + small preview. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/); absolute paths and ~ are used as-is",
      "output_format": "optional: csv | tsv | json | jsonl. If omitted, inferred from output_file extension (.csv/.tsv/.json/.jsonl/.ndjson); defaults to csv"
    }
    

  • Çıktı: output_file olmadan, başlık satırı ve satır sayısı özeti içeren CSV benzeri formatta sorgu sonuçlarını içeren metin içeriği. output_file ile, çözümlenen mutlak yol, bayt sayısı ve satır sayısını içeren kısa bir özet ve küçük bir önizleme. Başarısızlık durumunda bir hata mesajı döndürür.

• write_query

  • Açıklama: ResultSet döndürmeyen bir DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE) veya diğer StarRocks komutunu çalıştırın.
  • Girdi:

    {
      "query": "SQL command string",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Çıktı: Başarıyı doğrulayan metin içeriği (örn. "Sorgu OK, X satır etkilendi") veya bir hatayı bildiren metin. Değişiklikler başarı durumunda otomatik olarak kaydedilir.

• analyze_query

  • Açıklama: Sorgu profili veya açıklama analizini kullanarak bir sorguyu analiz edin ve analiz sonucunu alın.
  • Girdi:

    {
      "uuid": "Query ID, a string composed of 32 hexadecimal digits formatted as 8-4-4-4-12",
      "sql": "Query SQL to analyze",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Çıktı: Sorgu analiz sonuçlarını içeren metin içeriği. uuid sağlanırsa ANALYZE PROFILE FROM kullanır, aksi takdirde sql sağlanırsa EXPLAIN ANALYZE kullanır.

• top_hot_tables

  • Açıklama: Denetim günlüğü ziyaret sayısına göre en popüler tabloları alın. information_schema.tables ile starrocks_audit_db__.starrocks_audit_tbl__ birleştirir, root ve SHOW ifadelerini hariç tutar, denetim SQL metnini tablo adlarıyla eşleştirir ve visit_count azalan sıraya göre sıralar.
  • Girdi:

    {
      "db": "optional database/schema filter",
      "table": "optional table name substring filter",
      "min_start_time_ms": 1704067200000,
      "max_start_time_ms": 1704153600000,
      "top_n": 20
    }
    

  • Çıktı: db, table ve visit_count içeren sıralanmış satırları içeren metin özeti ve yapılandırılmış içerik.

• top_bad_tables

  • Açıklama: Star Management Studio'nun top-bad-tables mantığını izleyerek tablo sağlık puanına göre en kötü tabloları alın. information_schema.be_tablets ve information_schema.partitions_meta temel alınarak hesaplanan tablo sağlığı hesaplamasını yeniden kullanır, sistem şemalarını filtreler, table_health_score artan sıraya göre sıralar ve en düşük puanlı tabloları döndürür.
  • Girdi:

    {
      "db": "optional database/schema filter",
      "table": "optional table name substring filter",
      "top_n": 20
    }
    

  • Çıktı: db, table, tablet_num, replica_score, tablet_score ve table_health_score gibi tablo sağlık alanlarını içeren sıralanmış satırları içeren metin özeti ve yapılandırılmış içerik.

• query_and_plotly_chart

  • Açıklama: Bir SQL sorgusu çalıştırır, sonuçları bir Pandas DataFrame'e yükler ve sağlanan bir Python ifadesini kullanarak bir Plotly grafiği oluşturur. Destekleyen arayüzlerde görselleştirme için tasarlanmıştır.
  • Girdi:

    {
      "query": "SQL query to fetch data",
      "plotly_expr": "Python expression string using 'px' (Plotly Express) and 'df' (DataFrame). Example: 'px.scatter(df, x=\"col1\", y=\"col2\")'",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Çıktı: Aşağıdakileri içeren bir liste:
    1. TextContent: DataFrame'in metin gösterimi ve grafiğin arayüz görüntülemesi için olduğuna dair bir not.
    2. ImageContent: base64 PNG görüntüsü olarak kodlanmış oluşturulan Plotly grafiği (image/png). Başarısızlık durumunda veya sorgu veri döndürmezse metin hata mesajı döndürür.

• table_overview

  • Açıklama: Belirli bir tablonun genel bakışını alın: sütunlar (DESCRIBE'den), toplam satır sayısı ve örnek satırlar (LIMIT 3). refresh true olmadığı sürece bellek içi bir önbellek kullanır.
  • Girdi:

    {
      "table": "Table name, optionally prefixed with database name (e.g., 'db_name.table_name' or 'table_name'). If database is omitted, uses STARROCKS_DB environment variable if set.",
      "refresh": false // Optional, boolean. Set to true to bypass the cache. Defaults to false.
    }
    

  • Çıktı: Biçimlendirilmiş genel bakışı (sütunlar, satır sayısı, örnek veriler) veya bir hata mesajını içeren metin içeriği. Önbelleğe alınan sonuçlar, varsa önceki hataları da içerir.

• db_overview

  • Açıklama: Belirli bir veritabanındaki tüm tablolar için genel bakışı (sütunlar, satır sayısı, örnek satırlar) alın. refresh true olmadığı sürece her tablo için tablo düzeyinde önbelleği kullanır.
  • Girdi:

    {
      "db": "database_name", // Optional if default database is set.
      "refresh": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.
    }
    

  • Çıktı: Veritabanında bulunan tüm tablolar için başlıklarla ayrılmış birleştirilmiş genel bakışları içeren metin içeriği. Veritabanına erişilemezse veya tablo içermiyorsa bir hata mesajı döndürür.

Kaynaklar

Doğrudan Kaynaklar

• starrocks:///databases
  • Açıklama: Yapılandırılmış kullanıcının erişebildiği tüm veritabanlarını listeler.
  • Eşdeğer Sorgu: SHOW DATABASES
  • MIME Türü: text/plain

Kaynak Şablonları

• starrocks:///{db}/{table}/schema

  • Açıklama: Belirli bir tablonun şema tanımını alır.
  • Eşdeğer Sorgu: SHOW CREATE TABLE {db}.{table}
  • MIME Türü: text/plain

• starrocks:///{db}/tables

  • Açıklama: Belirli bir veritabanındaki tüm tabloları listeler.
  • Eşdeğer Sorgu: SHOW TABLES FROM {db}
  • MIME Türü: text/plain

• proc:///{+path}

  • Açıklama: Linux /proc komutuna benzer şekilde StarRocks dahili sistem bilgilerine erişir. path parametresi istenen bilgi düğümünü belirtir.
  • Eşdeğer Sorgu: SHOW PROC '/{path}'
  • MIME Türü: text/plain
  • Ortak Yollar:
    • /frontends - FE düğümleri hakkında bilgi.
    • /backends - BE düğümleri hakkında bilgi (bulut yerel olmayan dağıtımlar için).
    • /compute_nodes - CN düğümleri hakkında bilgi (bulut yerel dağıtımlar için).
    • /dbs - Veritabanları hakkında bilgi.
    • /dbs/<DB_ID> - Kimliğe göre belirli bir veritabanı hakkında bilgi.
    • /dbs/<DB_ID>/<TABLE_ID> - Kimliğe göre belirli bir tablo hakkında bilgi.
    • /dbs/<DB_ID>/<TABLE_ID>/partitions - Bir tablo için bölüm bilgisi.
    • /transactions - Veritabanına göre gruplandırılmış işlem bilgisi.
    • /transactions/<DB_ID> - Belirli bir veritabanı kimliği için işlem bilgisi.
    • /transactions/<DB_ID>/running - Bir veritabanı kimliği için çalışan işlemler.
    • /transactions/<DB_ID>/finished - Bir veritabanı kimliği için tamamlanan işlemler.
    • /jobs - Zaman uyumsuz işler hakkında bilgi (Şema Değişikliği, Rollup, vb.).
    • /statistic - Her veritabanı için istatistikler.
    • /tasks - Aracı görevleri hakkında bilgi.
    • /cluster_balance - Yük dengeleme durumu bilgisi.
    • /routine_loads - Routine Load işleri hakkında bilgi.
    • /colocation_group - Colocation Join grupları hakkında bilgi.
    • /catalog - Yapılandırılmış kataloglar hakkında bilgi (örn. Hive, Iceberg).

İstemler

Bu sunucu tarafından tanımlanmış istem yok.

Önbelleğe Alma Davranışı

• table_overview ve db_overview araçları, oluşturulan genel bakış metnini depolamak için bellek içi bir önbellek kullanır.
• Önbellek anahtarı, (database_name, table_name) öğesinden oluşan bir demettir.
• table_overview çağrıldığında önce önbelleği kontrol eder. Bir sonuç varsa ve refresh parametresi false (varsayılan) ise, önbelleğe alınan sonuç hemen döndürülür. Aksi takdirde, verileri StarRocks'tan alır, önbellekte saklar ve ardından döndürür.
• db_overview çağrıldığında, veritabanındaki tüm tabloları listeler ve ardından table_overview ile aynı önbelleğe alma mantığını kullanarak her tablo için genel bakışı almaya çalışır (önce önbelleği kontrol eder, gerekirse ve refresh false ise veya önbellek isabetsizliği varsa getirir). refresh true ise db_overview için, o veritabanındaki tüm tablolar için yenilemeyi zorlar.
• STARROCKS_OVERVIEW_LIMIT ortam değişkeni, önbelleği doldururken tablo başına oluşturulan genel bakış dizesinin maksimum uzunluğu için yumuşak bir hedef sağlar ve bellek kullanımını yönetmeye yardımcı olur.
• Önbelleğe alınan sonuçlar, orijinal getirme sırasında karşılaşılan hata mesajları dahil, saklanır ve sonraki önbellek isabetlerinde döndürülür.

Hata Ayıklama

mcp sunucusunu başlattıktan sonra hata ayıklamak için inspector kullanabilirsiniz:

npx @modelcontextprotocol/inspector

Demo