Citus MCP

🚀 Citus MCP 服務器

一款由人工智能驅動的 MCP 服務器，用於管理 Citus 分佈式 PostgreSQL 集群

本項目藉助先進的人工智能技術，為 Citus 分佈式 PostgreSQL 集群提供高效、智能的管理方案，能顯著提升集群的管理效率和穩定性。

快速開始 • 主要特性 • 安裝指南 • 配置說明 • 工具參考 • 使用示例

🚀 快速開始

前提條件

• Go 1.23 及以上版本（用於從源代碼構建）
• 可訪問協調器的 Citus 12.x - 14.x 集群
• 支持 MCP 的 GitHub Copilot（VS Code 或 CLI）

1. 構建服務器

git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp
make build
# 二進制文件將生成在 ./bin/citus-mcp

或者直接使用 Go 進行構建：

go build -o bin/citus-mcp ./cmd/citus-mcp

2. 配置連接

在 ~/.config/citus-mcp/config.yaml 中創建配置文件：

# 最低要求的配置
coordinator_dsn: postgres://username:password@localhost:5432/mydb?sslmode=disable

或者設置環境變量：

export CITUS_MCP_COORDINATOR_DSN="postgres://username:password@localhost:5432/mydb?sslmode=disable"

3. 設置 VS Code

在工作區創建 .vscode/mcp.json（或在項目根目錄創建 mcp.json）：

{
  "mcpServers": {
    "citus-mcp": {
      "command": "/path/to/citus-mcp/bin/citus-mcp",
      "args": [],
      "env": {
        "CITUS_MCP_COORDINATOR_DSN": "postgres://username:password@localhost:5432/mydb?sslmode=disable"
      }
    }
  }
}

4. 測試連接

在 VS Code Copilot 聊天中輸入：

@citus-mcp ping

若看到 "pong" 響應，則表明連接正常。

✨ 主要特性

🔍 集群檢查（只讀）

📊 監控與分析

🤖 智能顧問

⚡ 執行操作（需要批准）

📦 安裝指南

選項 1：從源代碼構建

# 克隆倉庫
git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp

# 使用 Make 進行構建
make build

# 或者直接使用 Go 構建
go build -o bin/citus-mcp ./cmd/citus-mcp

# （可選）安裝到系統路徑
sudo cp bin/citus-mcp /usr/local/bin/

選項 2：使用 Go 安裝

go install github.com/citusdata/citus-mcp/cmd/citus-mcp@latest

驗證安裝

citus-mcp --help

⚙️ 配置說明

連接字符串（DSN）

最重要的配置是指向 Citus 協調器的 PostgreSQL 連接字符串：

postgres://[用戶]:[密碼]@[主機]:[端口]/[數據庫]?sslmode=[模式]

示例：

# 本地開發（無 SSL）
postgres://postgres:secret@localhost:5432/mydb?sslmode=disable

# 生產環境使用 SSL
postgres://admin:secret@citus-coord.example.com:5432/production?sslmode=require

# 指定特定模式
postgres://user:pass@host:5432/db?sslmode=require&search_path=myschema

配置方法

配置可以通過以下方式提供（按優先級順序）：

1. 命令行標誌
2. 環境變量
3. 配置文件

方法 1：環境變量

# 必需
export CITUS_MCP_COORDINATOR_DSN="postgres://user:pass@localhost:5432/mydb?sslmode=disable"

# 可選
export CITUS_MCP_MODE="read_only"           # 只讀（默認）或管理員模式
export CITUS_MCP_ALLOW_EXECUTE="false"      # 啟用執行操作
export CITUS_MCP_APPROVAL_SECRET="secret"   # 如果 allow_execute=true 則必需
export CITUS_MCP_LOG_LEVEL="info"           # 調試、信息、警告、錯誤

方法 2：配置文件

創建 ~/.config/citus-mcp/config.yaml：

# ===========================================
# Citus MCP 服務器配置
# ===========================================

# 數據庫連接（必需）
# -----------------------------
coordinator_dsn: postgres://user:password@localhost:5432/mydb?sslmode=disable

# 可選：覆蓋 DSN 中的憑據
# coordinator_user: myuser
# coordinator_password: mypassword

# 可選：直接連接工作節點（逗號分隔）
# worker_dsns: postgres://user:pass@worker1:5432/db,postgres://user:pass@worker2:5432/db

# 服務器模式
# -----------
# read_only: 僅提供檢查工具（默認，最安全）
# admin: 提供所有工具，包括執行操作
mode: read_only

# 執行操作（僅當 mode=admin 時）
# ---------------------------------------
allow_execute: false
# approval_secret: your-secret-key  # 如果 allow_execute=true 則必需

# 性能設置
# --------------------
cache_ttl_seconds: 5          # 元數據查詢的緩存持續時間
enable_caching: true          # 設置為 false 可禁用緩存
max_rows: 200                 # 每個查詢返回的最大行數
max_text_bytes: 200000        # 響應中的最大文本大小

# 超時設置
# --------
connect_timeout_seconds: 10   # 連接超時時間
statement_timeout_ms: 30000   # 查詢超時時間（30 秒）

# 日誌記錄
# -------
log_level: info               # 調試、信息、警告、錯誤

# 傳輸方式（新增）
# ---------------
# stdio: 標準輸入/輸出（默認，用於 VS Code/CLI 集成）
# sse: 通過 HTTP 的服務器發送事件（用於遠程/網絡訪問）
# streamable: 可流式傳輸的 HTTP 傳輸（用於遠程/網絡訪問）
transport: stdio

# HTTP 設置（僅當傳輸方式為 sse 或 streamable 時使用）
# http_addr: 127.0.0.1        # 監聽地址（使用 0.0.0.0 表示所有接口）
# http_port: 8080             # 監聽端口
# http_path: /mcp             # 端點路徑
# sse_keepalive_seconds: 30   # SSE 保持活動間隔

方法 3：命令行標誌

# 使用標誌（注意：標誌名使用下劃線）
bin/citus-mcp --coordinator_dsn "postgres://..." --mode read_only

# 使用位置參數指定 DSN
bin/citus-mcp "postgres://user:pass@localhost:5432/mydb?sslmode=disable"

# 指定配置文件
bin/citus-mcp --config /path/to/config.yaml

# 使用 SSE 傳輸方式啟動
bin/citus-mcp --transport sse --http_port 8080 --coordinator_dsn "postgres://..."

配置文件位置

服務器按以下順序搜索配置文件：

1. --config / -c 標誌
2. CITUS_MCP_CONFIG 環境變量
3. $XDG_CONFIG_HOME/citus-mcp/config.yaml
4. ~/.config/citus-mcp/config.yaml
5. ./citus-mcp.yaml（當前目錄）

支持的格式：YAML、JSON、TOML

🌐 傳輸選項

Citus MCP 支持三種傳輸模式，以適應不同的部署場景：

1. 標準輸入/輸出傳輸（默認）

標準輸入/輸出傳輸方式，服務器通過標準輸入/輸出進行通信。這是默認模式，用於與 VS Code 和 GitHub Copilot CLI 直接集成。

# 默認 - 標準輸入/輸出傳輸
bin/citus-mcp --coordinator_dsn "postgres://..."

# 顯式指定
bin/citus-mcp --transport stdio --coordinator_dsn "postgres://..."

使用場景：

• VS Code Copilot 聊天集成
• GitHub Copilot CLI
• 本地開發

2. SSE 傳輸（服務器發送事件）

基於 HTTP 的傳輸方式，使用服務器發送事件。服務器作為 HTTP 守護進程運行，客戶端可以遠程連接。

# 使用 SSE 在 HTTP 上啟動服務器
bin/citus-mcp --transport sse --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."

# 或者通過環境變量設置
export CITUS_MCP_TRANSPORT=sse
export CITUS_MCP_HTTP_ADDR=0.0.0.0
export CITUS_MCP_HTTP_PORT=8080
export CITUS_MCP_COORDINATOR_DSN="postgres://..."
bin/citus-mcp

端點：

• GET /mcp - 建立 SSE 連接
• POST /mcp/session/{id} - 向會話發送消息
• GET /health - 健康檢查

使用場景：

• 遠程 MCP 服務器部署
• Docker/Kubernetes 部署
• 多客戶端共享服務器
• 網絡可訪問的 MCP 服務

3. 可流式傳輸的 HTTP 傳輸

具有流式支持的現代 HTTP 傳輸方式，推薦用於新的部署。

# 使用可流式傳輸的 HTTP 傳輸啟動服務器
bin/citus-mcp --transport streamable --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."

端點：

• POST /mcp - 處理 MCP 請求並提供流式響應
• GET /health - 健康檢查

使用場景：

• 與 SSE 相同，但具有更好的流式支持
• SSE 不理想的環境

Docker 部署示例

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o citus-mcp ./cmd/citus-mcp

FROM alpine:latest
COPY --from=builder /app/citus-mcp /usr/local/bin/
EXPOSE 8080
CMD ["citus-mcp", "--transport", "sse", "--http-addr", "0.0.0.0", "--http-port", "8080"]

# docker-compose.yml
version: '3.8'
services:
  citus-mcp:
    build: .
    ports:
      - "8080:8080"
    environment:
      CITUS_MCP_TRANSPORT: sse
      CITUS_MCP_HTTP_ADDR: 0.0.0.0
      CITUS_MCP_HTTP_PORT: 8080
      CITUS_MCP_COORDINATOR_DSN: postgres://user:pass@citus-coordinator:5432/mydb?sslmode=disable

連接到遠程服務器

對於 SSE/可流式傳輸的傳輸方式，配置 MCP 客戶端通過 HTTP 連接：

{
  "mcpServers": {
    "citus-mcp": {
      "type": "sse",
      "url": "http://citus-mcp-server:8080/mcp"
    }
  }
}

🔌 與 GitHub Copilot 集成設置

VS Code 設置

1. 安裝先決條件
   • 安裝帶有 GitHub Copilot 擴展的 VS Code
   • 在 Copilot 設置中啟用 MCP 支持
2. 創建 MCP 配置 在工作區創建 .vscode/mcp.json：

   {
     "mcpServers": {
       "citus-mcp": {
         "command": "/absolute/path/to/bin/citus-mcp",
         "args": [],
         "env": {
           "CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
         }
       }
     }
   }
   

   或者用於開發（使用 go run）：

   {
     "mcpServers": {
       "citus-mcp": {
         "command": "go",
         "args": ["run", "./cmd/citus-mcp"],
         "cwd": "/path/to/citus-mcp",
         "env": {
           "CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
         }
       }
     }
   }
   

3. 重新加載 VS Code 並打開 Copilot 聊天
4. 驗證連接

   @citus-mcp ping
   

GitHub Copilot CLI 設置

1. 創建全局 MCP 配置 創建 ~/.config/github-copilot/mcp.json：

   {
     "mcpServers": {
       "citus-mcp": {
         "command": "/usr/local/bin/citus-mcp",
         "args": [],
         "env": {
           "CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
         }
       }
     }
   }
   

2. 驗證設置

   copilot mcp list
   copilot mcp test citus-mcp
   

3. 在 CLI 中使用

   copilot -p "Show me the cluster summary"
   

💻 使用示例

基礎集群檢查

@citus-mcp Show me the cluster summary

@citus-mcp List all distributed tables

@citus-mcp Inspect the public.users table including shards and indexes

監控

@citus-mcp Show current cluster activity

@citus-mcp Are there any lock waits in the cluster?

@citus-mcp Show background job progress

分析

@citus-mcp Analyze shard skew for the orders table

@citus-mcp Show me the shard heatmap grouped by node

@citus-mcp Explain this query: SELECT * FROM orders WHERE customer_id = 123

顧問

@citus-mcp Run the advisor with focus on skew

@citus-mcp Check operational health (long queries, locks, jobs)

@citus-mcp Suggest the best source node for snapshot-based scaling

@citus-mcp Check metadata health with deep validation across nodes

配置分析

@citus-mcp Analyze cluster configuration and recommend improvements

@citus-mcp Run config advisor with focus on memory settings

共置分析

@citus-mcp Show all colocation groups

@citus-mcp Which tables are colocated with the orders table?

節點添加

@citus-mcp Run pre-flight checks for adding node at postgres://user:pass@newworker:5432/db

📚 工具參考

檢查工具

監控工具

顧問工具

執行工具（需要批准）

📋 內置提示

在 Copilot 聊天中使用這些提示以獲得引導式工作流程：

🔐 安全說明

只讀模式（默認）

默認情況下，citus-mcp 以 只讀模式 運行。這意味著：

• ✅ 所有檢查和監控工具均可正常使用
• ✅ 顧問提供建議
• ❌ 執行操作被禁用
• ❌ 無法修改數據

管理員模式與批准令牌

要啟用執行操作：

1. 在配置中設置管理員模式：

   mode: admin
   allow_execute: true
   approval_secret: your-secret-key-here
   

2. 執行前請求批准令牌：

   @citus-mcp Request approval token for rebalance
   

3. 在執行命令中使用令牌：

   @citus-mcp Execute rebalance with token: <token>
   

令牌具有時間限制且特定於操作（使用 HMAC 簽名）。

🔧 故障排除

連接問題

錯誤：connection refused

• 驗證協調器主機和端口是否正確
• 檢查 PostgreSQL 是否正在運行並接受連接
• 確保防火牆規則允許連接

錯誤：authentication failed

• 驗證 DSN 中的用戶名和密碼
• 檢查用戶是否對數據庫具有權限
• 對於 SSL 問題，本地測試時可嘗試 sslmode=disable

MCP 問題

Copilot 無法識別 citus-mcp

• 確保 mcp.json 位於正確位置
• 檢查命令路徑是否為絕對路徑
• 修改配置後重新加載 VS Code

工具返回錯誤

• 查看日誌：CITUS_MCP_LOG_LEVEL=debug bin/citus-mcp
• 驗證 Citus 擴展是否已安裝：SELECT * FROM pg_extension WHERE extname = 'citus'

測試連接

# 直接測試
CITUS_MCP_COORDINATOR_DSN="postgres://..." bin/citus-mcp

# 然後通過標準輸入發送 ping 請求
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | bin/citus-mcp

🛠️ 開發說明

運行測試

# 單元測試
make test

# 詳細輸出
go test -v ./...

# 集成測試（需要 Docker）
make docker-up
make integration
make docker-down

代碼檢查

make lint

項目結構

citus-mcp/
├── cmd/citus-mcp/       # 主入口點
├── internal/
│   ├── mcpserver/       # MCP 服務器實現
│   │   ├── tools/       # 工具實現（30 多個工具）
│   │   ├── prompts/     # 提示模板
│   │   └── resources/   # 靜態資源
│   ├── db/              # 數據庫層和工作節點管理
│   ├── citus/           # Citus 特定邏輯和查詢
│   │   ├── advisor/     # 顧問實現
│   │   └── guc/         # GUC（配置）分析
│   ├── cache/           # 查詢結果緩存
│   ├── config/          # 配置管理
│   ├── errors/          # 錯誤類型和代碼
│   ├── fanout