StarRocks

เซิร์ฟเวอร์ MCP อย่างเป็นทางการของ StarRocks

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

คุณสมบัติ

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

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

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

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

# 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 การกำหนดค่าจะถูกส่งไปยังโฮสต์ โดยระบุวิธีการเปิดใช้กระบวนการเซิร์ฟเวอร์ MCP ของ StarRocks

การใช้ 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"
    }
  }
}

การใช้ 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 ของบริการ StarRocks FE ค่าเริ่มต้นคือ localhost
• STARROCKS_PORT: (ไม่บังคับ) พอร์ตโปรโตคอล MySQL ของบริการ StarRocks FE ค่าเริ่มต้นคือ 9030
• STARROCKS_USER: (ไม่บังคับ) ชื่อผู้ใช้ StarRocks ค่าเริ่มต้นคือ root
• STARROCKS_PASSWORD: (ไม่บังคับ) รหัสผ่าน StarRocks ค่าเริ่มต้นคือสตริงว่าง
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (ไม่บังคับ, เฉพาะ macOS) ชื่อบริการรหัสผ่านทั่วไปที่จะใช้เมื่ออ่านรหัสผ่านจาก Keychain จะใช้เฉพาะเมื่อไม่มีการระบุรหัสผ่านอย่างชัดเจนผ่าน STARROCKS_PASSWORD หรือ STARROCKS_URL
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (ไม่บังคับ, เฉพาะ macOS) ชื่อบัญชีรหัสผ่านทั่วไปที่จะใช้เมื่ออ่านรหัสผ่านจาก Keychain ค่าเริ่มต้นคือผู้ใช้ StarRocks ที่แก้ไขแล้ว
• STARROCKS_DB: (ไม่บังคับ) ฐานข้อมูลเริ่มต้นที่จะใช้หากไม่ได้ระบุในอาร์กิวเมนต์ของเครื่องมือหรือ URI ทรัพยากร หากตั้งค่าไว้ การเชื่อมต่อจะพยายาม USE ฐานข้อมูลนี้ เครื่องมือเช่น table_overview และ db_overview จะใช้ค่านี้หากส่วนของฐานข้อมูลถูกละไว้ในอาร์กิวเมนต์ ค่าเริ่มต้นคือว่างเปล่า (ไม่มีฐานข้อมูลเริ่มต้น)

ตัวเลือกที่ 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_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

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

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (ไม่บังคับ) พอร์ต Arrow Flight SQL ของบริการ StarRocks FE เมื่อตั้งค่าไว้ เซิร์ฟเวอร์จะเชื่อมต่อโดยใช้โปรโตคอล 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") ค่าเริ่มต้นคือไดเรกทอรี temp ของระบบ ไดเรกทอรีจะถูกสร้างขึ้นเมื่อต้องการ หมายเหตุ: เช่นเดียวกับไฟล์เอาต์พุตอื่นๆ แผนภูมิจะถูกเขียนบนเครื่องที่เซิร์ฟเวอร์ 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: (ไม่บังคับ) ระบุปลั๊กอินการตรวจสอบสิทธิ์ที่จะใช้เมื่อเชื่อมต่อกับบริการ StarRocks FE ตัวอย่างเช่น ตั้งค่าเป็น 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:// แบบข้อความธรรมดา เมื่อเปิดใช้งาน STARROCKS_SSL_CA จะถูกใช้เป็นใบรับรอง root ของ TLS และ STARROCKS_SSL_VERIFY_CERT=false (ค่าเริ่มต้น) จะข้ามการตรวจสอบใบรับรองเซิร์ฟเวอร์

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

• MCP_TRANSPORT_MODE: (ไม่บังคับ) โหมดการสื่อสารที่ระบุวิธีที่เซิร์ฟเวอร์ MCP เปิดเผยบริการของตน ตัวเลือกที่มี:
  • stdio (ค่าเริ่มต้น): สื่อสารผ่านอินพุต/เอาต์พุตมาตรฐาน เหมาะสำหรับการโฮสต์ MCP Host
  • streamable-http (Streamable HTTP): เริ่มต้นเป็นเซิร์ฟเวอร์ Streamable HTTP รองรับการเรียก API แบบ RESTful
  • 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") หรือรายงานข้อผิดพลาด การเปลี่ยนแปลงจะถูกคอมมิตโดยอัตโนมัติเมื่อสำเร็จ

• 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 โดยเชื่อม information_schema.tables กับ starrocks_audit_db__.starrocks_audit_tbl__ ยกเว้นคำสั่ง root และ SHOW จับคู่ข้อความ SQL จาก audit กับชื่อตาราง และเรียงลำดับตาม 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 มาใช้ใหม่ กรอง schema ระบบออก เรียงลำดับตาม 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 ที่สร้างขึ้นซึ่งเข้ารหัสเป็นรูปภาพ base64 PNG (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

  • คำอธิบาย: รับนิยาม 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 - ข้อมูลเกี่ยวกับ agent tasks
    • /cluster_balance - ข้อมูลสถานะ load 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 คุณสามารถใช้ inspector เพื่อดีบัก:

npx @modelcontextprotocol/inspector

การสาธิต