StarRocks

StarRocks Official MCP Server

StarRocks MCP Server ทำหน้าที่เป็นสะพานเชื่อมระหว่างผู้ช่วย AI และฐานข้อมูล StarRocks โดยอนุญาตให้ดำเนินการ SQL โดยตรง สำรวจฐานข้อมูล แสดงข้อมูลเป็นภาพผ่านแผนภูมิ และดึงข้อมูลโครงสร้าง/ภาพรวมข้อมูลโดยละเอียดโดยไม่ต้องตั้งค่าฝั่งไคลเอนต์ที่ซับซ้อน

คุณสมบัติ

• ดำเนินการ SQL โดยตรง: รันคำสั่ง SELECT (read_query) และคำสั่ง DDL/DML (write_query)
• สำรวจฐานข้อมูล: แสดงรายการฐานข้อมูลและตาราง ดึงโครงสร้างตาราง (ทรัพยากร starrocks://)
• ข้อมูลระบบ: เข้าถึงเมตริกและสถานะภายในของ StarRocks ผ่านเส้นทางทรัพยากร proc://
• ภาพรวมโดยละเอียด: รับสรุปที่ครอบคลุมของตาราง (table_overview) หรือฐานข้อมูลทั้งหมด (db_overview) รวมถึงคำจำกัดความของคอลัมน์ จำนวนแถว และข้อมูลตัวอย่าง
• การแสดงข้อมูลเป็นภาพ: ดำเนินการคิวรีและสร้างแผนภูมิ Plotly โดยตรงจากผลลัพธ์ (query_and_plotly_chart)
• แคชอัจฉริยะ: ภาพรวมตารางและฐานข้อมูลถูกแคชในหน่วยความจำเพื่อเพิ่มความเร็วในการร้องขอซ้ำ โดยสามารถข้ามแคชได้เมื่อจำเป็น
• การกำหนดค่าที่ยืดหยุ่น: ตั้งค่ารายละเอียดการเชื่อมต่อและพฤติกรรมผ่านตัวแปรสภาพแวดล้อม

ข้อกำหนดเบื้องต้น

• Python 3.11 หรือใหม่กว่า
• คลัสเตอร์ StarRocks ที่เข้าถึงได้ (บริการ FE) โดยค่าเริ่มต้นเซิร์ฟเวอร์จะเชื่อมต่อกับ localhost:9030 ผ่านโปรโตคอล MySQL
• uv — แพ็กเกจ Python และตัวจัดการโปรเจกต์ที่รวดเร็ว (ตัวแทนสมัยใหม่ของ pip + virtualenv) จาก Astral โปรเจกต์นี้ใช้ uv เพื่อแก้ไขการพึ่งพา สร้างสภาพแวดล้อมเสมือน และเปิดใช้เซิร์ฟเวอร์ คำสั่ง uv run ตลอดทั้ง README นี้จะสร้างสภาพแวดล้อมที่แยกออกมาโดยอัตโนมัติและติดตั้งการพึ่งพาที่จำเป็นในการใช้งานครั้งแรก ดังนั้นจึงไม่จำเป็นต้องดำเนินการ pip install ด้วยตนเอง

การติดตั้ง uv

# 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

ดู คู่มือการติดตั้ง uv อย่างเป็นทางการ สำหรับตัวเลือกอื่น ๆ หลังการติดตั้ง ตรวจสอบว่าอยู่ใน PATH ของคุณ:

uv --version

การติดตั้ง

โดยทั่วไปคุณ ไม่ จำเป็นต้องติดตั้งแพ็กเกจด้วยตนเอง — โฮสต์ MCP จะเปิดใช้ให้คุณผ่าน uv (ดู การกำหนดค่า ด้านล่าง) uv จะดึงแพ็กเกจและการพึ่งพาตามความต้องการ

เพื่อรันโดยตรงสำหรับการทดสอบหรือการพัฒนา:

# 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

การกำหนดค่า

เซิร์ฟเวอร์ MCP มักถูกเรียกใช้ผ่านโฮสต์ MCP การกำหนดค่าจะถูกส่งไปยังโฮสต์ โดยระบุวิธีเปิดใช้กระบวนการเซิร์ฟเวอร์ StarRocks MCP

การใช้ Streamable HTTP (แนะนำ):

เพื่อเริ่มเซิร์ฟเวอร์ในโหมด Streamable HTTP:

ขั้นแรกทดสอบว่าการเชื่อมต่อกับ StarRocks ทำงานได้ (9030 คือพอร์ตโปรโตคอล MySQL ของ StarRocks ไม่ใช่พอร์ตเซิร์ฟเวอร์ HTTP):

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

เริ่มเซิร์ฟเวอร์:

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

จากนั้นกำหนดค่า MCP ดังนี้:

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

การใช้ Docker:

สร้างอิมเมจ:

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

สร้างและพุชอิมเมจที่มีเวอร์ชัน:

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

เริ่มเซิร์ฟเวอร์ในโหมด Streamable HTTP:

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

จากนั้นกำหนดค่าไคลเอนต์ MCP ด้วย:

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

การใช้ uv กับแพ็กเกจที่ติดตั้งแล้ว (ตัวแปรสภาพแวดล้อมรายบุคคล):

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

การใช้ uv กับแพ็กเกจที่ติดตั้งแล้ว (URL การเชื่อมต่อ):

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

การใช้ uv กับไดเรกทอรีท้องถิ่น (สำหรับการพัฒนา):

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

การใช้ uv กับไดเรกทอรีท้องถิ่นและ URL การเชื่อมต่อ:

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

อาร์กิวเมนต์บรรทัดคำสั่ง:

เซิร์ฟเวอร์รองรับอาร์กิวเมนต์บรรทัดคำสั่งต่อไปนี้:

uv run mcp-server-starrocks --help

• --mode {stdio,sse,http,streamable-http}: โหมดการขนส่ง (ค่าเริ่มต้น: stdio หรือตัวแปรสภาพแวดล้อม MCP_TRANSPORT_MODE)
• --host HOST: โฮสต์เซิร์ฟเวอร์สำหรับโหมด HTTP (ค่าเริ่มต้น: localhost)
• --port PORT: พอร์ตเซิร์ฟเวอร์สำหรับโหมด HTTP
• --test: รันในโหมดทดสอบเพื่อตรวจสอบฟังก์ชันการทำงาน

ตัวอย่าง:

# 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 ควรชี้ไปที่จุดสิ้นสุด Streamable HTTP ของเซิร์ฟเวอร์ MCP ของคุณ (ปรับโฮสต์/พอร์ตตามความจำเป็น)
• ด้วยการกำหนดค่านี้ ไคลเอนต์สามารถโต้ตอบกับเซิร์ฟเวอร์โดยใช้ JSON มาตรฐานผ่านคำขอ HTTP POST ไม่จำเป็นต้องใช้ SDK พิเศษ
• API เครื่องมือทั้งหมดรับและส่งคืน JSON มาตรฐานตามที่อธิบายไว้ข้างต้น

หมายเหตุ: โหมด sse (Server-Sent Events) ถูกเลิกใช้และไม่ได้รับการบำรุงรักษาอีกต่อไป โปรดใช้โหมด Streamable HTTP สำหรับการรวมระบบใหม่ทั้งหมด

ตัวแปรสภาพแวดล้อม:

การกำหนดค่าการเชื่อมต่อ

คุณสามารถกำหนดค่าการเชื่อมต่อ StarRocks โดยใช้ตัวแปรสภาพแวดล้อมรายบุคคลหรือ URL การเชื่อมต่อเดียว:

ตัวเลือก 1: ตัวแปรสภาพแวดล้อมรายบุคคล

• STARROCKS_HOST: (ไม่บังคับ) ชื่อโฮสต์หรือที่อยู่ IP ของบริการ FE ของ StarRocks ค่าเริ่มต้นคือ localhost
• STARROCKS_PORT: (ไม่บังคับ) พอร์ตโปรโตคอล MySQL ของบริการ FE ของ StarRocks ค่าเริ่มต้นคือ 9030
• STARROCKS_USER: (ไม่บังคับ) ชื่อผู้ใช้ StarRocks ค่าเริ่มต้นคือ root
• STARROCKS_PASSWORD: (ไม่บังคับ) รหัสผ่าน StarRocks ค่าเริ่มต้นคือสตริงว่าง
• STARROCKS_PASSWORD_FILE: (ไม่บังคับ) เส้นทางไปยังไฟล์ข้อความ UTF-8 ที่มีรหัสผ่าน ซึ่งมีประโยชน์กับการฉีดความลับแบบไฟล์ เช่น ข้อมูลประจำตัว systemd การขึ้นบรรทัดใหม่ต่อท้ายหนึ่งครั้งจะถูกละเว้น ใช้เฉพาะเมื่อไม่มีรหัสผ่านที่ชัดเจนผ่าน STARROCKS_PASSWORD หรือ STARROCKS_URL
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (ไม่บังคับ, เฉพาะ macOS) ชื่อบริการรหัสผ่านทั่วไปที่จะใช้เมื่ออ่านรหัสผ่านจาก Keychain ใช้เฉพาะเมื่อไม่มีรหัสผ่านที่ชัดเจนหรือ STARROCKS_PASSWORD_FILE ถูกกำหนดค่า
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (ไม่บังคับ, เฉพาะ macOS) ชื่อบัญชีรหัสผ่านทั่วไปที่จะใช้เมื่ออ่านรหัสผ่านจาก Keychain ค่าเริ่มต้นคือผู้ใช้ StarRocks ที่ถูกแก้ไข
• STARROCKS_DB: (ไม่บังคับ) ฐานข้อมูลเริ่มต้นที่จะใช้หากไม่ได้ระบุในอาร์กิวเมนต์เครื่องมือหรือ URI ทรัพยากร หากตั้งค่า การเชื่อมต่อจะพยายาม USE ฐานข้อมูลนี้ เครื่องมือเช่น table_overview และ db_overview จะใช้ค่านี้หากละเว้นส่วนฐานข้อมูลในอาร์กิวเมนต์ ค่าเริ่มต้นคือว่าง (ไม่มีฐานข้อมูลเริ่มต้น)
• STARROCKS_QUERY_TIMEOUT: (ไม่บังคับ) จำนวนวินาทีที่จะรอผลลัพธ์ของคิวรีก่อนยอมแพ้ เป็นจำนวนเต็ม ไม่ได้ตั้งค่าโดยค่าเริ่มต้น ซึ่งรออย่างไม่มีกำหนด ตรงกับพฤติกรรมก่อนหน้า ตั้งค่านี้หากคิวรีที่ค้างหรือใช้เวลานานควรล้มเหลวแทนที่จะบล็อกการเรียกเครื่องมือตลอดไป

ตัวเลือก 2: URL การเชื่อมต่อ (มีความสำคัญเหนือกว่าตัวแปรรายบุคคล)

• STARROCKS_URL: (ไม่บังคับ) สตริง URL การเชื่อมต่อที่มีพารามิเตอร์การเชื่อมต่อทั้งหมดในตัวแปรเดียว รูปแบบ: [<schema>://]user:password@host:port/database ส่วน schema เป็นตัวเลือก เมื่อตั้งค่าตัวแปรนี้ จะมีความสำคัญเหนือกว่าตัวแปร STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD และ STARROCKS_DB รายบุคคล

  ตัวอย่าง:

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

ลำดับความสำคัญของรหัสผ่าน:

• รหัสผ่านที่ฝังใน STARROCKS_URL ชนะ รวมถึงรหัสผ่านว่างที่ชัดเจนเช่น user:@host:9030/db
• หาก STARROCKS_URL ละเว้นรหัสผ่าน จะใช้ STARROCKS_PASSWORD เมื่อตั้งค่า
• หากไม่มีแหล่งรหัสผ่านที่ชัดเจนและ STARROCKS_PASSWORD_FILE ถูกกำหนดค่า รหัสผ่านจะถูกอ่านจากไฟล์นั้น
• หากไม่มีรหัสผ่านที่ชัดเจนหรือไฟล์รหัสผ่านที่กำหนดค่าและ STARROCKS_PASSWORD_KEYCHAIN_SERVICE ถูกตั้งค่า รหัสผ่านจะถูกอ่านจาก macOS Keychain

ตัวอย่าง macOS Keychain

จัดเก็บรหัสผ่าน:

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

ตรวจสอบรหัสผ่านที่จัดเก็บ:

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

ใช้กับเซิร์ฟเวอร์นี้:

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

ตัวอย่างข้อมูลประจำตัวที่เข้ารหัส systemd (systemd 250 หรือใหม่กว่า)

เซิร์ฟเวอร์ไม่เรียกใช้ systemd-creds เอง ในเวลาปรับใช้ ผู้ดูแลระบบจะเข้ารหัสรหัสผ่าน ที่เริ่มบริการ systemd จะถอดรหัสลงในไดเรกทอรีข้อมูลประจำตัวของบริการและเปิดเผยเฉพาะเส้นทางไฟล์ให้เซิร์ฟเวอร์นี้

สร้างข้อมูลประจำตัวที่เข้ารหัสผูกกับโฮสต์โดยไม่ใส่รหัสผ่านในประวัติเชลล์:

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

เพิ่มข้อมูลประจำตัวในหน่วยบริการ ตัวระบุ %d ขยายเป็นไดเรกทอรีข้อมูลประจำตัวเฉพาะบริการ:

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

ปล่อยให้ STARROCKS_PASSWORD ไม่ได้ตั้งค่าและละเว้นรหัสผ่านจาก STARROCKS_URL จากนั้นโหลดหน่วยใหม่และรีสตาร์ทบริการ ข้อมูลประจำตัวที่เข้ารหัสมักถูกผูกกับโฮสต์ท้องถิ่น (และกับอุปกรณ์ TPM2 เมื่อมี) จะถูกถอดรหัสเฉพาะเมื่อบริการกำลังถูกเปิดใช้เท่านั้น กระบวนการบริการและผู้ดูแลระบบที่มีสิทธิ์ root ยังสามารถเข้าถึงรหัสผ่านข้อความธรรมดาได้ในเวลารันไทม์ อย่าใช้ systemd-creds encrypt --with-key=null ซึ่งไม่ให้การรักษาความลับ

การกำหนดค่าเพิ่มเติม

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (ไม่บังคับ) พอร์ต Arrow Flight SQL ของบริการ FE ของ StarRocks เมื่อตั้งค่า เซิร์ฟเวอร์จะเชื่อมต่อโดยใช้โปรโตคอล Arrow Flight SQL ประสิทธิภาพสูง (ผ่านไดรเวอร์ ADBC) แทนโปรโตคอล MySQL มาตรฐาน ปล่อยว่างไว้เพื่อใช้การเชื่อมต่อ MySQL เริ่มต้น โฮสต์ ผู้ใช้ และรหัสผ่านถูกนำมาจากการตั้งค่าการเชื่อมต่อเดียวกันตามที่อธิบายไว้ข้างต้น

• STARROCKS_OVERVIEW_LIMIT: (ไม่บังคับ) ขีดจำกัดอักขระ โดยประมาณ สำหรับ ทั้งหมด ของข้อความที่สร้างโดยเครื่องมือภาพรวม (table_overview, db_overview) เมื่อดึงข้อมูลเพื่อเติมแคช ซึ่งช่วยป้องกันการใช้หน่วยความจำมากเกินไปสำหรับ schema ที่ใหญ่มากหรือตารางจำนวนมาก ค่าเริ่มต้นคือ 20000

• STARROCKS_MCP_OUTPUT_DIR: (ไม่บังคับ) ไดเรกทอรีที่ใช้โดย read_query เมื่ออาร์กิวเมนต์ output_file เป็นเส้นทางสัมพัทธ์ ค่าเริ่มต้นคือ ~/.mcp-server-starrocks/output/ ไดเรกทอรีถูกสร้างตามความต้องการ เส้นทางสัมบูรณ์ที่ส่งไปยัง output_file (รวมถึงเส้นทางที่นำหน้าด้วย ~) ข้ามการตั้งค่านี้ หมายเหตุ: ไฟล์ถูกเขียนบนเครื่องที่เซิร์ฟเวอร์ MCP รัน สำหรับ Claude Code / Claude Desktop เซิร์ฟเวอร์รันในเครื่อง ดังนั้นไฟล์จะอยู่บนแล็ปท็อปของคุณ สำหรับการปรับใช้ระยะไกล/http ไฟล์จะอยู่บนเซิร์ฟเวอร์ ไม่ใช่ไคลเอนต์

• STARROCKS_CHART_OUTPUT_DIR: (ไม่บังคับ) ไดเรกทอรีที่ query_and_plotly_chart เขียนแผนภูมิ HTML แบบโต้ตอบ (เมื่อ format="html") ค่าเริ่มต้นคือไดเรกทอรีชั่วคราวของระบบ ไดเรกทอรีถูกสร้างตามความต้องการ หมายเหตุ: เช่นเดียวกับไฟล์เอาต์พุตอื่น ๆ แผนภูมิถูกเขียนบนเครื่องที่เซิร์ฟเวอร์ MCP รัน

• STARROCKS_CHART_INCLUDE_PLOTLYJS: (ไม่บังคับ) ควบคุมวิธีที่ plotly.js ถูกรวมเป็นบันเดิลในแผนภูมิ HTML cdn (ค่าเริ่มต้น) ทำให้ไฟล์มีขนาดเล็กแต่ต้องใช้เครือข่ายเมื่อดู inline/true ฝังไลบรารีเต็มสำหรับการใช้งานออฟไลน์ directory และ false ก็ได้รับการยอมรับเช่นกัน (ส่งผ่านไปยัง write_html ของ Plotly)

• STARROCKS_CHART_DEFAULT_FORMAT: (ไม่บังคับ) รูปแบบเอาต์พุตเริ่มต้นสำหรับ query_and_plotly_chart เมื่อละเว้นอาร์กิวเมนต์ format หนึ่งใน json, png, jpeg (ค่าเริ่มต้น) หรือ html ตั้งค่าเป็น html เพื่อเขียนไฟล์แผนภูมิแบบโต้ตอบไปยัง STARROCKS_CHART_OUTPUT_DIR เสมอ (พร้อมตัวอย่าง PNG แบบอินไลน์) โดยไม่ต้องส่ง format ในการเรียกทุกครั้ง ค่าที่ไม่ถูกต้องจะกลับไปเป็น jpeg พร้อมคำเตือน

• STARROCKS_MYSQL_AUTH_PLUGIN: (ไม่บังคับ) ระบุปลั๊กอินการตรวจสอบสิทธิ์ที่จะใช้เมื่อเชื่อมต่อกับบริการ FE ของ StarRocks ตัวอย่างเช่น ตั้งค่าเป็น mysql_clear_password หากการปรับใช้ StarRocks ของคุณต้องการการตรวจสอบสิทธิ์รหัสผ่านข้อความธรรมดา (เช่นเมื่อใช้การตั้งค่า LDAP หรือการตรวจสอบสิทธิ์ภายนอกบางอย่าง) ตั้งค่านี้เฉพาะเมื่อสภาพแวดล้อมของคุณต้องการจริง ๆ มิฉะนั้นจะใช้ auth_plugin เริ่มต้น

การกำหนดค่า TLS / SSL

ตัวแปรเหล่านี้ควบคุม TLS สำหรับการเชื่อมต่อ เมื่อไม่มีตัวแปรใดถูกตั้งค่า mysql.connector พื้นฐานจะรักษาพฤติกรรมเริ่มต้น (ssl-mode=PREFERRED): การเชื่อมต่อถูกเข้ารหัสหากเซิร์ฟเวอร์รองรับ TLS แต่ใบรับรองเซิร์ฟเวอร์ ไม่ ถูกตรวจสอบ สำหรับความปลอดภัยจริง ให้ระบุใบรับรอง CA และเปิดใช้งานการตรวจสอบ

• STARROCKS_SSL_DISABLED: (ไม่บังคับ) ตั้งค่าเป็น true เพื่อบังคับปิดใช้งาน TLS ซึ่งจะแทนที่การตั้งค่า SSL อื่นๆ ทั้งหมด ค่าเริ่มต้นคือ false
• STARROCKS_SSL_CA: (ไม่บังคับ) เส้นทางไปยังใบรับรอง CA (PEM) ที่ใช้ตรวจสอบใบรับรองเซิร์ฟเวอร์ StarRocks
• STARROCKS_SSL_CERT: (ไม่บังคับ) เส้นทางไปยังใบรับรองไคลเอ็นต์ (PEM) สำหรับ mutual TLS (mTLS)
• STARROCKS_SSL_KEY: (ไม่บังคับ) เส้นทางไปยังคีย์ส่วนตัวของไคลเอ็นต์ (PEM) สำหรับ mutual TLS (mTLS)
• STARROCKS_SSL_VERIFY_CERT: (ไม่บังคับ) ตั้งค่าเป็น true เพื่อตรวจสอบใบรับรองเซิร์ฟเวอร์กับ CA ค่าเริ่มต้นคือ false
• STARROCKS_SSL_VERIFY_IDENTITY: (ไม่บังคับ) ตั้งค่าเป็น true เพื่อตรวจสอบว่าโฮสต์เนมของเซิร์ฟเวอร์ตรงกับใบรับรองด้วย ค่าเริ่มต้นคือ false
• STARROCKS_TLS_VERSIONS: (ไม่บังคับ) รายการเวอร์ชัน TLS ที่อนุญาต คั่นด้วยเครื่องหมายจุลภาค เช่น TLSv1.2,TLSv1.3

ตัวอย่าง (ตรวจสอบเซิร์ฟเวอร์กับใบรับรอง CA):

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

สำหรับการเชื่อมต่อ Arrow Flight SQL ประสิทธิภาพสูง (เปิดใช้งานผ่าน STARROCKS_FE_ARROW_FLIGHT_SQL_PORT) TLS จะถูกควบคุมแยกต่างหาก:

• STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS: (ไม่บังคับ) ตั้งค่าเป็น true เพื่อใช้ grpc+tls:// แทน grpc:// แบบ plaintext เมื่อเปิดใช้งาน STARROCKS_SSL_CA จะถูกใช้เป็นใบรับรองราก TLS และ STARROCKS_SSL_VERIFY_CERT=false (ค่าเริ่มต้น) จะข้ามการตรวจสอบใบรับรองเซิร์ฟเวอร์

หมายเหตุด้านความปลอดภัย: หลีกเลี่ยงการเก็บรหัสผ่านแบบ plaintext โดยตรงใน mcp.json ควรฉีด STARROCKS_PASSWORD (และเส้นทางใบรับรอง) จากตัวจัดการความลับหรือสภาพแวดล้อม และไม่ควร commit ข้อมูลรับรองลงในระบบควบคุมเวอร์ชัน

• MCP_TRANSPORT_MODE: (ไม่บังคับ) โหมดการสื่อสารที่ระบุว่า MCP Server เปิดเผยบริการอย่างไร ตัวเลือกที่มี:
  • stdio (ค่าเริ่มต้น): สื่อสารผ่าน standard input/output เหมาะสำหรับการโฮสต์ MCP Host
  • streamable-http (Streamable HTTP): เริ่มต้นเป็น Streamable HTTP Server รองรับการเรียก RESTful API
  • sse: (เลิกใช้งานแล้ว ไม่แนะนำ) เริ่มต้นในโหมดสตรีมมิ่ง Server-Sent Events (SSE) เหมาะสำหรับสถานการณ์ที่ต้องการการตอบสนองแบบสตรีม หมายเหตุ: โหมด SSE ไม่ได้รับการบำรุงรักษาอีกต่อไป แนะนำให้ใช้โหมด Streamable HTTP อย่างสม่ำเสมอ

คอมโพเนนต์

เครื่องมือ

• read_query

  • คำอธิบาย: ดำเนินการคิวรี SELECT หรือคำสั่งอื่นๆ ที่ส่งคืน ResultSet (เช่น SHOW, DESCRIBE) คุณสามารถเขียนผลลัพธ์ทั้งหมดลงในไฟล์ท้องถิ่นแทนการส่งคืนแบบอินไลน์ได้ ซึ่งมีประโยชน์สำหรับผลลัพธ์ที่ใหญ่เกินไปที่จะใส่ในบริบทของโมเดล
  • อินพุต:

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

  • เอาต์พุต: หากไม่มี output_file จะเป็นเนื้อหาข้อความที่มีผลลัพธ์คิวรีในรูปแบบคล้าย CSV พร้อมแถวหัวข้อและสรุปจำนวนแถว หากมี output_file จะเป็นสรุปสั้นๆ รวมถึงเส้นทางสัมบูรณ์ที่แก้ไขแล้ว จำนวนไบต์ และจำนวนแถว พร้อมตัวอย่างเล็กน้อย ส่งคืนข้อความแสดงข้อผิดพลาดเมื่อล้มเหลว

• write_query

  • คำอธิบาย: ดำเนินการคำสั่ง DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE) หรือคำสั่ง StarRocks อื่นๆ ที่ไม่ส่งคืน ResultSet
  • อินพุต:

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

  • เอาต์พุต: เนื้อหาข้อความที่ยืนยันความสำเร็จ (เช่น "Query OK, X rows affected") หรือรายงานข้อผิดพลาด การเปลี่ยนแปลงจะถูก commit โดยอัตโนมัติเมื่อสำเร็จ

• analyze_query

  • คำอธิบาย: วิเคราะห์คิวรีและรับผลการวิเคราะห์โดยใช้ query profile หรือ explain analyze
  • อินพุต:

    {
      "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)"
    }
    

  • เอาต์พุต: เนื้อหาข้อความที่มีผลการวิเคราะห์คิวรี ใช้ ANALYZE PROFILE FROM หากระบุ uuid มิฉะนั้นจะใช้ EXPLAIN ANALYZE หากระบุ sql

• top_hot_tables

  • คำอธิบาย: รับตารางยอดนิยมตามจำนวนการเข้าชมจาก audit-log โดย join information_schema.tables กับ starrocks_audit_db__.starrocks_audit_tbl__ ไม่รวมคำสั่ง root และ SHOW จับคู่ข้อความ SQL จากการตรวจสอบกับชื่อตาราง และเรียงตาม visit_count จากมากไปน้อย
  • อินพุต:

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

  • เอาต์พุต: สรุปข้อความบวกกับเนื้อหาที่มีโครงสร้างซึ่งมีแถวที่จัดอันดับพร้อม db, table และ visit_count

• top_bad_tables

  • คำอธิบาย: รับตารางที่แย่ที่สุดตามคะแนนสุขภาพตาราง ตามตรรกะ top-bad-tables ของ Star Management Studio โดยใช้การคำนวณสุขภาพตารางตาม information_schema.be_tablets และ information_schema.partitions_meta กรองสคีมาของระบบออก เรียงตาม table_health_score จากน้อยไปมาก และส่งคืนตารางที่มีคะแนนต่ำสุด
  • อินพุต:

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

  • เอาต์พุต: สรุปข้อความบวกกับเนื้อหาที่มีโครงสร้างซึ่งมีแถวที่จัดอันดับพร้อมฟิลด์สุขภาพตาราง เช่น db, table, tablet_num, replica_score, tablet_score และ table_health_score

• query_and_plotly_chart

  • คำอธิบาย: ดำเนินการคิวรี SQL โหลดผลลัพธ์ลงใน Pandas DataFrame และสร้างแผนภูมิ Plotly โดยใช้นิพจน์ Python ที่ให้มา ออกแบบมาสำหรับการแสดงภาพใน UI ที่รองรับ
  • อินพุต:

    {
      "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)"
    }
    

  • เอาต์พุต: รายการที่ประกอบด้วย:
    1. TextContent: การแสดงข้อความของ DataFrame และหมายเหตุว่าแผนภูมิมีไว้สำหรับแสดงใน UI
    2. ImageContent: แผนภูมิ Plotly ที่สร้างขึ้นซึ่งเข้ารหัสเป็นภาพ PNG base64 (image/png) ส่งคืนข้อความแสดงข้อผิดพลาดเมื่อล้มเหลวหรือหากคิวรีไม่มีข้อมูล

• table_overview

  • คำอธิบาย: รับภาพรวมของตารางเฉพาะ: คอลัมน์ (จาก DESCRIBE), จำนวนแถวทั้งหมด และแถวตัวอย่าง (LIMIT 3) ใช้แคชในหน่วยความจำเว้นแต่ refresh เป็น true
  • อินพุต:

    {
      "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.
    }
    

  • เอาต์พุต: เนื้อหาข้อความที่มีภาพรวมที่จัดรูปแบบ (คอลัมน์ จำนวนแถว ข้อมูลตัวอย่าง) หรือข้อความแสดงข้อผิดพลาด ผลลัพธ์ที่แคชไว้รวมถึงข้อผิดพลาดก่อนหน้าหากมี

• db_overview

  • คำอธิบาย: รับภาพรวม (คอลัมน์ จำนวนแถว แถวตัวอย่าง) สำหรับ ทุก ตารางภายในฐานข้อมูลที่ระบุ ใช้แคชระดับตารางสำหรับแต่ละตารางเว้นแต่ refresh เป็น true
  • อินพุต:

    {
      "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.
    }
    

  • เอาต์พุต: เนื้อหาข้อความที่มีภาพรวมที่ต่อกันสำหรับทุกตารางที่พบในฐานข้อมูล คั่นด้วยส่วนหัว ส่งคืนข้อความแสดงข้อผิดพลาดหากไม่สามารถเข้าถึงฐานข้อมูลหรือไม่มีตาราง

ทรัพยากร

ทรัพยากรโดยตรง

• starrocks:///databases
  • คำอธิบาย: แสดงรายการฐานข้อมูลทั้งหมดที่ผู้ใช้ที่กำหนดค่าสามารถเข้าถึงได้
  • คิวรีเทียบเท่า: SHOW DATABASES
  • ประเภท MIME: text/plain

เทมเพลตทรัพยากร

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

  • คำอธิบาย: รับคำจำกัดความสคีมาของตารางเฉพาะ
  • คิวรีเทียบเท่า: SHOW CREATE TABLE {db}.{table}
  • ประเภท MIME: text/plain

• starrocks:///{db}/tables

  • คำอธิบาย: แสดงรายการตารางทั้งหมดภายในฐานข้อมูลเฉพาะ
  • คิวรีเทียบเท่า: SHOW TABLES FROM {db}
  • ประเภท MIME: text/plain

• proc:///{+path}

  • คำอธิบาย: เข้าถึงข้อมูลระบบภายในของ StarRocks คล้ายกับ /proc ของ Linux พารามิเตอร์ path ระบุโหนดข้อมูลที่ต้องการ
  • คิวรีเทียบเท่า: SHOW PROC '/{path}'
  • ประเภท MIME: text/plain
  • เส้นทางทั่วไป:
    • /frontends - ข้อมูลเกี่ยวกับโหนด FE
    • /backends - ข้อมูลเกี่ยวกับโหนด BE (สำหรับการปรับใช้แบบไม่ใช่ cloud native)
    • /compute_nodes - ข้อมูลเกี่ยวกับโหนด CN (สำหรับการปรับใช้แบบ cloud native)
    • /dbs - ข้อมูลเกี่ยวกับฐานข้อมูล
    • /dbs/<DB_ID> - ข้อมูลเกี่ยวกับฐานข้อมูลเฉพาะตาม ID
    • /dbs/<DB_ID>/<TABLE_ID> - ข้อมูลเกี่ยวกับตารางเฉพาะตาม ID
    • /dbs/<DB_ID>/<TABLE_ID>/partitions - ข้อมูลพาร์ติชันสำหรับตาราง
    • /transactions - ข้อมูลธุรกรรมจัดกลุ่มตามฐานข้อมูล
    • /transactions/<DB_ID> - ข้อมูลธุรกรรมสำหรับ ID ฐานข้อมูลเฉพาะ
    • /transactions/<DB_ID>/running - ธุรกรรมที่กำลังทำงานสำหรับ ID ฐานข้อมูล
    • /transactions/<DB_ID>/finished - ธุรกรรมที่เสร็จสิ้นสำหรับ ID ฐานข้อมูล
    • /jobs - ข้อมูลเกี่ยวกับงานแบบอะซิงโครนัส (Schema Change, Rollup ฯลฯ)
    • /statistic - สถิติสำหรับแต่ละฐานข้อมูล
    • /tasks - ข้อมูลเกี่ยวกับงานตัวแทน
    • /cluster_balance - ข้อมูลสถานะการปรับสมดุลโหลด
    • /routine_loads - ข้อมูลเกี่ยวกับงาน Routine Load
    • /colocation_group - ข้อมูลเกี่ยวกับกลุ่ม Colocation Join
    • /catalog - ข้อมูลเกี่ยวกับแคตตาล็อกที่กำหนดค่า (เช่น Hive, Iceberg)

พรอมต์

ไม่มีการกำหนดโดยเซิร์ฟเวอร์นี้

พฤติกรรมแคช

• เครื่องมือ table_overview และ db_overview ใช้แคชในหน่วยความจำเพื่อเก็บข้อความภาพรวมที่สร้างขึ้น
• คีย์แคชคือทูเพิลของ (database_name, table_name)
• เมื่อเรียก table_overview จะตรวจสอบแคชก่อน หากมีผลลัพธ์และพารามิเตอร์ refresh เป็น false (ค่าเริ่มต้น) ผลลัพธ์ที่แคชไว้จะถูกส่งคืนทันที มิฉะนั้นจะดึงข้อมูลจาก StarRocks เก็บไว้ในแคช แล้วส่งคืน
• เมื่อเรียก db_overview จะแสดงรายการตารางทั้งหมดในฐานข้อมูล จากนั้นพยายามดึงภาพรวมสำหรับ แต่ละตาราง โดยใช้ตรรกะแคชเดียวกันกับ table_overview (ตรวจสอบแคชก่อน ดึงข้อมูลหากจำเป็นและ refresh เป็น false หรือแคชพลาด) หาก refresh เป็น true สำหรับ db_overview จะบังคับรีเฟรชสำหรับ ทุก ตารางในฐานข้อมูลนั้น
• ตัวแปรสภาพแวดล้อม STARROCKS_OVERVIEW_LIMIT ให้ เป้าหมายแบบอ่อน สำหรับความยาวสูงสุดของสตริงภาพรวมที่สร้างขึ้น ต่อตาราง เมื่อเติมแคช ช่วยจัดการการใช้หน่วยความจำ
• ผลลัพธ์ที่แคชไว้ รวมถึงข้อความแสดงข้อผิดพลาดที่พบระหว่างการดึงข้อมูลครั้งแรก จะถูกเก็บและส่งคืนในการเข้าถึงแคชครั้งถัดไป

การดีบัก

หลังจากเริ่ม mcp server คุณสามารถใช้ inspector เพื่อดีบัก:

npx @modelcontextprotocol/inspector

เดโม