StarRocks MCP Server

resmi

StarRocks ile etkileşim kurun

Dokümantasyon

StarRocks Resmi MCP Sunucusu

StarRocks MCP Sunucusu, yapay zeka 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 özetleri almayı sağlar.

Özellikler

Doğrudan SQL Yürütme: SELECT sorguları (read_query) ve DDL/DML komutları (write_query) çalıştırın.
Veritabanı Keşfi: Veritabanlarını ve tabloları listeleyin, tablo şemalarını alın (starrocks:// kaynakları).
Sistem Bilgisi: proc:// kaynak yolu üzerinden dahili StarRocks metriklerine ve durumlarına erişin.
Ayrıntılı Özetler: Sütun tanımları, satır sayıları ve örnek veriler dahil olmak üzere tabloların (table_overview) veya tüm veritabanlarının (db_overview) kapsamlı özetlerini alın.
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ı detaylarını ve davranışı ortam değişkenleri aracılığıyla ayarlayın.

Ön Koşullar

Python 3.11 veya daha yenisi.
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 paket 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'deki uv run komutları, ilk kullanımda otomatik olarak yalıtılmış bir ortam oluşturur ve gerekli bağımlılıkları yükler, bu nedenle manuel bir pip install adımına gerek yoktur.

`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 resmi uv kurulum kılavuzuna bakın. Kurulumdan sonra, PATH üzerinde olduğunu doğrulayın:

uv --version

Kurulum

Genellikle paketi manuel olarak kurmanıza gerek yoktur — MCP ana bilgisayarı 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ı talep üzerine 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 sunucu sürecinin nasıl başlatılacağını belirterek ana bilgisayara iletilir.

Akışkan HTTP Kullanımı (önerilir):

Sunucuyu Akışkan HTTP modunda başlatmak için:

Önce StarRocks bağlantısının tamam olduğunu test edin (9030, HTTP sunucu portu değil, StarRocks MySQL protokol portudur):

$ 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"
    }
  }
}

Yüklü 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"
      }
    }
  }
}

Yüklü 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ı Argümanları:

Sunucu aşağıdaki komut satırı argümanlarını 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 portu
--test: İşlevselliği doğrulamak için test modunda çalıştır

Ö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 Akışkan HTTP uç noktasına işaret etmelidir (ana bilgisayar/portu gerektiği gibi ayarlayın).
Bu yapılandırma ile istemciler, HTTP POST istekleri üzerinden standart JSON kullanarak sunucuyla etkileşime girebilir. Ö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 Olaylar) modu kullanımdan kaldırılmıştır ve artık bakımı yapılmamaktadır. Tüm yeni entegrasyonlar için lütfen Akışkan HTTP modunu kullanın.

Ortam Değişkenleri:

Bağlantı Yapılandırması

StarRocks bağlantısını bireysel ortam değişkenleri veya tek bir bağlantı URL'si 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.
STARROCKS_PORT: (İsteğe bağlı) StarRocks FE hizmetinin MySQL protokol portu. Varsayılan: 9030.
STARROCKS_USER: (İsteğe bağlı) StarRocks kullanıcı adı. Varsayılan: root.
STARROCKS_PASSWORD: (İsteğe bağlı) StarRocks parolası. Varsayılan: boş dize.
STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (İsteğe bağlı, yalnızca macOS) Parolayı Anahtar Zincirinden okurken kullanılacak genel parola hizmet adı. Bu, yalnızca STARROCKS_PASSWORD veya STARROCKS_URL aracılığıyla açık bir parola sağlanmadığında kullanılır.
STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (İsteğe bağlı, yalnızca macOS) Parolayı Anahtar Zincirinden okurken kullanılacak genel parola hesap adı. Varsayılan: çözümlenen StarRocks kullanıcısı.
STARROCKS_DB: (İsteğe bağlı) Araç argümanlarında veya kaynak URI'lerinde belirtilmezse kullanılacak varsayılan veritabanı. Ayarlanırsa, bağlantı bu veritabanına USE yapmaya çalışır. table_overview ve db_overview gibi araçlar, argümanlarında veritabanı kısmı atlanırsa bunu kullanır. Varsayılan: boş (varsayılan veritabanı yok).

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 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:[email protected]:9030/production
- starrocks://user:[email protected]:9030/analytics

Parola önceliği:

STARROCKS_URL içine gömülü bir parola, user:@host:9030/db gibi açık bir boş parola da dahil olmak üzere kazanır.
STARROCKS_URL parolayı atlarsa, ayarlandığında STARROCKS_PASSWORD kullanılır.
Hiçbir açık parola kaynağı ayarlanmamışsa ve STARROCKS_PASSWORD_KEYCHAIN_SERVICE yapılandırılmışsa, parola macOS Anahtar Zincirinden okunur.

macOS Anahtar Zinciri ö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

Ek Yapılandırma

STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (İsteğe bağlı) StarRocks FE hizmetinin Arrow Flight SQL portu. Ayarlandığında, 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 getirirken özet araçları (table_overview, db_overview) tarafından oluşturulan 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.
STARROCKS_MCP_OUTPUT_DIR: (İsteğe bağlı) read_query argümanı göreli bir yol olduğunda output_file tarafından kullanılan dizin. Varsayılan: ~/.mcp-server-starrocks/output/. Dizin talep üzerine oluşturulur. output_file'e iletilen mutlak yollar (~ ön ekli 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 iner. Uzak/http dağıtımları için dosya istemciye değil sunucuya iner.
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 açık metin parola kimlik doğrulaması gerektiriyorsa (belirli LDAP veya harici kimlik doğrulama kurulumlarında olduğu gibi) mysql_clear_password olarak ayarlayın. Bunu yalnızca ortamınız özellikle gerektiriyorsa ayarlayın; aksi takdirde varsayılan auth_plugin kullanılır.
MCP_TRANSPORT_MODE: (İsteğe bağlı) MCP Sunucusunun hizmetlerini nasıl sunduğunu belirten iletişim modu. Mevcut seçenekler:
- stdio (varsayılan): MCP Ana Bilgisayar barındırmaya uygun, standart giriş/çıkış üzerinden iletişim kurar.
- 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) Akış yanıtları gerektiren senaryolar için uygun, Sunucu Tarafından Gönderilen Olaylar (SSE) akış modunda başlar. Not: SSE modunun 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 bir ResultSet döndüren diğer komutları yürütü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 ile CSV benzeri biçimde 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ı ile küçük bir önizleme dahil kısa bir özet. Başarısızlık durumunda bir hata mesajı döndürür.
write_query
- Açıklama: Bir ResultSet döndürmeyen bir DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE) veya diğer StarRocks komutunu yürütün.
- Girdi:
```
{
  "query": "SQL command string",
  "db": "database name (optional, uses default database if not specified)"
}
```
- Çıktı: Başarıyı onaylayan (örn., "Query OK, X rows affected") veya bir hata bildiren metin içeriği. Değişiklikler başarı durumunda otomatik olarak kaydedilir.
analyze_query
- Açıklama: Sorgu profilini veya explain analyze'ı 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 analizi sonuçlarını içeren metin içeriği. uuid sağlanmışsa ANALYZE PROFILE FROM kullanır, aksi takdirde sql sağlanmışsa EXPLAIN ANALYZE kullanır.
query_and_plotly_chart
- Açıklama: Bir SQL sorgusu yürütür, sonuçları bir Pandas DataFrame'e yükler ve sağlanan bir Python ifadesi kullanarak bir Plotly grafiği oluşturur. Destekleyen kullanıcı arayüzlerinde 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 bir metin temsili ve grafiğin kullanıcı arayüzü gösterimi 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 hiç veri döndürmezse metin hata mesajı döndürür.
table_overview
- Açıklama: Belirli bir tablonun özetini alın: sütunlar (DESCRIBE'dan), toplam satır sayısı ve örnek satırlar (LIMIT 3). refresh true olmadıkça bellek içi ö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ş özeti (sütunlar, satır sayısı, örnek veri) veya bir hata mesajını içeren metin içeriği. Önbelleğe alınmış sonuçlar, varsa önceki hataları içerir.
db_overview
- Açıklama: Belirtilen bir veritabanındaki tüm tablolar için bir özet (sütunlar, satır sayısı, örnek satırlar) alın. refresh true olmadıkça 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ş özetleri içeren metin içeriği. Veritabanına erişilemezse veya hiç tablo içermiyorsa bir hata mesajı döndürür.

Kaynaklar

Doğrudan Kaynaklar

starrocks:///databases
- Açıklama: Yapılandırılan 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
- Yaygın Yollar:
  - /frontends - FE düğümleri hakkında bilgi.
  - /backends - BE düğümleri hakkında bilgi (bulut tabanlı olmayan dağıtımlar için).
  - /compute_nodes - CN düğümleri hakkında bilgi (bulut tabanlı 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 tamamlanmış işlemler.
  - /jobs - Eşzamansız 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 durum bilgisi.
  - /routine_loads - Rutin Yükleme işleri hakkında bilgi.
  - /colocation_group - Ortak Konum Birleştirme grupları hakkında bilgi.
  - /catalog - Yapılandırılmış kataloglar hakkında bilgi (ör. Hive, Iceberg).

İstemler

Bu sunucu tarafından hiçbiri tanımlanmamıştır.

Önbellekleme 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) öğesinin bir demetidir.
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, StarRocks'tan verileri alır, önbellekte depolar ve sonra döndürür.
db_overview çağrıldığında, veritabanındaki tüm tabloları listeler ve ardından table_overview ile aynı önbellekleme mantığını kullanarak her tablo için genel bakışı almaya çalışır (önce önbelleği kontrol eder, gerekirse ve refresh false ise veya önbellek kaçırması varsa getirir). refresh, db_overview için true ise, 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 bir yumuşak hedef sağlar ve bellek kullanımını yönetmeye yardımcı olur.
Orijinal getirme sırasında karşılaşılan hata mesajları da dahil olmak üzere önbelleğe alınan sonuçlar, sonraki önbellek isabetlerinde saklanır ve 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

MCP Demo Image