{"id":46212185,"url":"https://github.com/codeforall/citus-mcp","last_synced_at":"2026-03-03T09:18:17.754Z","repository":{"id":334172994,"uuid":"1139775173","full_name":"codeforall/citus-mcp","owner":"codeforall","description":"🤖 AI-powered MCP server for Citus distributed PostgreSQL. Built in collaboration with GitHub Copilot.","archived":false,"fork":false,"pushed_at":"2026-01-23T06:53:56.000Z","size":311,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-24T00:11:00.694Z","etag":null,"topics":["ai-powered","citus","cluster-management","distributed-database","github-copilot","go","golang","mcp","model-context-protocol","postgresql","sql"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeforall.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-22T11:56:47.000Z","updated_at":"2026-01-23T06:54:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codeforall/citus-mcp","commit_stats":null,"previous_names":["codeforall/citus-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/codeforall/citus-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforall%2Fcitus-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforall%2Fcitus-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforall%2Fcitus-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforall%2Fcitus-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeforall","download_url":"https://codeload.github.com/codeforall/citus-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforall%2Fcitus-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30038912,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T06:58:30.252Z","status":"ssl_error","status_checked_at":"2026-03-03T06:58:15.329Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-powered","citus","cluster-management","distributed-database","github-copilot","go","golang","mcp","model-context-protocol","postgresql","sql"],"created_at":"2026-03-03T09:18:15.144Z","updated_at":"2026-03-03T09:18:17.741Z","avatar_url":"https://github.com/codeforall.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/images/logo.png\" alt=\"citus-mcp logo\" width=\"180\"/\u003e\n\n# Citus MCP Server\n\n**An AI-powered MCP server for managing Citus distributed PostgreSQL clusters**\n\n[![Go Version](https://img.shields.io/badge/Go-1.23+-00ADD8?style=flat\u0026logo=go)](https://golang.org)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Citus](https://img.shields.io/badge/Citus-12.x--14.x-336791?logo=postgresql)](https://www.citusdata.com)\n\n[Quick Start](#-quick-start) •\n[Features](#-features) •\n[Installation](#-installation) •\n[Configuration](#-configuration) •\n[Tools Reference](#-tools-reference) •\n[Examples](#-usage-examples)\n\n\u003c/div\u003e\n\n---\n\n## 📖 What is Citus MCP?\n\nCitus MCP is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like GitHub Copilot to interact with your Citus distributed PostgreSQL cluster. It provides:\n\n| Feature | Description |\n|---------|-------------|\n| 🔍 **Read-only Inspection** | Safely explore distributed tables, shards, nodes, and colocation groups |\n| 🤖 **Intelligent Advisors** | Get recommendations for rebalancing, skew analysis, configuration, and operational health |\n| 🛡️ **Guarded Operations** | Execute dangerous operations only with explicit approval tokens |\n| 📊 **Real-time Monitoring** | View cluster activity, locks, background jobs, and hot shards |\n\n### How It Works\n\n```\n┌─────────────────┐                      ┌──────────────┐                ┌─────────────────┐\n│  GitHub Copilot │     MCP Protocol     │  citus-mcp   │      SQL       │  Citus Cluster  │\n│  (VS Code/CLI)  │ \u003c──────────────────\u003e │    server    │ \u003c────────────\u003e │  (Coordinator)  │\n└─────────────────┘      stdio/SSE       └──────────────┘                └─────────────────┘\n```\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Go 1.23+** (for building from source)\n- **Citus 12.x–14.x** cluster with coordinator access\n- **GitHub Copilot** with MCP support (VS Code or CLI)\n\n### 1. Build the Server\n\n```bash\ngit clone https://github.com/citusdata/citus-mcp.git\ncd citus-mcp\nmake build\n# Binary created at ./bin/citus-mcp\n```\n\nOr using Go directly:\n\n```bash\ngo build -o bin/citus-mcp ./cmd/citus-mcp\n```\n\n### 2. Configure Your Connection\n\nCreate a configuration file at `~/.config/citus-mcp/config.yaml`:\n\n```yaml\n# Minimum required configuration\ncoordinator_dsn: postgres://username:password@localhost:5432/mydb?sslmode=disable\n```\n\nOr set the environment variable:\n\n```bash\nexport CITUS_MCP_COORDINATOR_DSN=\"postgres://username:password@localhost:5432/mydb?sslmode=disable\"\n```\n\n### 3. Set Up VS Code\n\nCreate `.vscode/mcp.json` in your workspace (or `mcp.json` at the project root):\n\n```json\n{\n  \"mcpServers\": {\n    \"citus-mcp\": {\n      \"command\": \"/path/to/citus-mcp/bin/citus-mcp\",\n      \"args\": [],\n      \"env\": {\n        \"CITUS_MCP_COORDINATOR_DSN\": \"postgres://username:password@localhost:5432/mydb?sslmode=disable\"\n      }\n    }\n  }\n}\n```\n\n### 4. Test the Connection\n\nIn VS Code Copilot Chat, type:\n\n```\n@citus-mcp ping\n```\n\nYou should see a \"pong\" response confirming the connection works.\n\n---\n\n## ✨ Features\n\n### 🔍 Cluster Inspection (Read-Only)\n\n| Tool | Description |\n|------|-------------|\n| `citus_cluster_summary` | Overview of coordinator, workers, table counts, and configuration health |\n| `list_nodes` | List all coordinator and worker nodes |\n| `list_distributed_tables` | List distributed and reference tables |\n| `citus_list_distributed_tables` | Paginated list of distributed tables with filters |\n| `citus_list_reference_tables` | Paginated list of reference tables |\n| `list_shards` | List shards with placements and sizes |\n| `citus_table_inspector` | Deep dive into table metadata, indexes, and statistics |\n| `citus_colocation_inspector` | Analyze colocation groups and colocated tables |\n\n### 📊 Monitoring \u0026 Analysis\n\n| Tool | Description |\n|------|-------------|\n| `citus_activity` | Cluster-wide active queries and connections |\n| `citus_lock_inspector` | View lock waits and blocking queries |\n| `citus_job_inspector` | Background job progress (rebalance, copy) |\n| `citus_shard_heatmap` | Hot shards and node distribution |\n| `citus_shard_skew_report` | Data skew analysis per node |\n| `citus_explain_query` | EXPLAIN distributed queries |\n\n### 🤖 Intelligent Advisors\n\n| Tool | Description |\n|------|-------------|\n| `citus_advisor` | SRE + performance advisor with actionable recommendations |\n| `citus_config_advisor` | Comprehensive Citus and PostgreSQL configuration analysis |\n| `citus_snapshot_source_advisor` | Recommend source node for snapshot-based scaling |\n| `citus_validate_rebalance_prereqs` | Check if table is ready for rebalancing |\n| `citus_metadata_health` | Detect metadata corruption and inconsistencies with fix suggestions |\n| `citus_node_prepare_advisor` | Pre-flight checks and preparation script for adding new nodes |\n\n### ⚡ Execute Operations (Requires Approval)\n\n| Tool | Description |\n|------|-------------|\n| `citus_rebalance_plan` | Preview rebalance operations |\n| `citus_rebalance_execute` | Start cluster rebalance |\n| `citus_rebalance_status` | Monitor rebalance progress |\n| `citus_move_shard_plan` | Preview shard move |\n| `citus_move_shard_execute` | Move a shard to different node |\n| `citus_request_approval_token` | Request time-limited approval token |\n\n---\n\n## 📦 Installation\n\n### Option 1: Build from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/citusdata/citus-mcp.git\ncd citus-mcp\n\n# Build using Make\nmake build\n\n# Or build directly with Go\ngo build -o bin/citus-mcp ./cmd/citus-mcp\n\n# (Optional) Install to your PATH\nsudo cp bin/citus-mcp /usr/local/bin/\n```\n\n### Option 2: Go Install\n\n```bash\ngo install github.com/citusdata/citus-mcp/cmd/citus-mcp@latest\n```\n\n### Verify Installation\n\n```bash\ncitus-mcp --help\n```\n\n---\n\n## ⚙️ Configuration\n\n### Connection String (DSN)\n\nThe most important configuration is the PostgreSQL connection string to your Citus coordinator:\n\n```\npostgres://[user]:[password]@[host]:[port]/[database]?sslmode=[mode]\n```\n\n**Examples:**\n\n```bash\n# Local development (no SSL)\npostgres://postgres:secret@localhost:5432/mydb?sslmode=disable\n\n# Production with SSL\npostgres://admin:secret@citus-coord.example.com:5432/production?sslmode=require\n\n# With specific schema\npostgres://user:pass@host:5432/db?sslmode=require\u0026search_path=myschema\n```\n\n### Configuration Methods\n\nConfiguration can be provided via (in order of precedence):\n\n1. **Command-line flags**\n2. **Environment variables**\n3. **Configuration file**\n\n#### Method 1: Environment Variables\n\n```bash\n# Required\nexport CITUS_MCP_COORDINATOR_DSN=\"postgres://user:pass@localhost:5432/mydb?sslmode=disable\"\n\n# Optional\nexport CITUS_MCP_MODE=\"read_only\"           # read_only (default) or admin\nexport CITUS_MCP_ALLOW_EXECUTE=\"false\"      # Enable execute operations\nexport CITUS_MCP_APPROVAL_SECRET=\"secret\"   # Required if allow_execute=true\nexport CITUS_MCP_LOG_LEVEL=\"info\"           # debug, info, warn, error\n```\n\n#### Method 2: Configuration File\n\nCreate `~/.config/citus-mcp/config.yaml`:\n\n```yaml\n# ===========================================\n# Citus MCP Server Configuration\n# ===========================================\n\n# Database Connection (REQUIRED)\n# -----------------------------\ncoordinator_dsn: postgres://user:password@localhost:5432/mydb?sslmode=disable\n\n# Optional: Override credentials from DSN\n# coordinator_user: myuser\n# coordinator_password: mypassword\n\n# Optional: Direct worker connections (comma-separated)\n# worker_dsns: postgres://user:pass@worker1:5432/db,postgres://user:pass@worker2:5432/db\n\n# Server Mode\n# -----------\n# read_only: Only inspection tools available (default, safest)\n# admin: All tools available including execute operations\nmode: read_only\n\n# Execute Operations (only if mode=admin)\n# ---------------------------------------\nallow_execute: false\n# approval_secret: your-secret-key  # Required if allow_execute=true\n\n# Performance Settings\n# --------------------\ncache_ttl_seconds: 5          # Cache duration for metadata queries\nenable_caching: true          # Set to false to disable caching\nmax_rows: 200                 # Maximum rows returned per query\nmax_text_bytes: 200000        # Maximum text size in responses\n\n# Timeouts\n# --------\nconnect_timeout_seconds: 10   # Connection timeout\nstatement_timeout_ms: 30000   # Query timeout (30 seconds)\n\n# Logging\n# -------\nlog_level: info               # debug, info, warn, error\n\n# Transport (NEW)\n# ---------------\n# stdio: Standard input/output (default, for VS Code/CLI integration)\n# sse: Server-Sent Events over HTTP (for remote/network access)\n# streamable: Streamable HTTP transport (for remote/network access)\ntransport: stdio\n\n# HTTP Settings (only used when transport is sse or streamable)\n# http_addr: 127.0.0.1        # Listen address (use 0.0.0.0 for all interfaces)\n# http_port: 8080             # Listen port\n# http_path: /mcp             # Endpoint path\n# sse_keepalive_seconds: 30   # SSE keepalive interval\n```\n\n#### Method 3: Command-Line Flags\n\n```bash\n# Using flags (note: use underscores in flag names)\nbin/citus-mcp --coordinator_dsn \"postgres://...\" --mode read_only\n\n# Using positional argument for DSN\nbin/citus-mcp \"postgres://user:pass@localhost:5432/mydb?sslmode=disable\"\n\n# Specify config file\nbin/citus-mcp --config /path/to/config.yaml\n\n# Start with SSE transport\nbin/citus-mcp --transport sse --http_port 8080 --coordinator_dsn \"postgres://...\"\n```\n\n### Configuration File Locations\n\nThe server searches for configuration files in this order:\n\n1. `--config` / `-c` flag\n2. `CITUS_MCP_CONFIG` environment variable\n3. `$XDG_CONFIG_HOME/citus-mcp/config.yaml`\n4. `~/.config/citus-mcp/config.yaml`\n5. `./citus-mcp.yaml` (current directory)\n\nSupported formats: YAML, JSON, TOML\n\n---\n\n## 🌐 Transport Options\n\nCitus MCP supports three transport modes for different deployment scenarios:\n\n### 1. Stdio Transport (Default)\n\nStandard input/output transport — the server communicates via stdin/stdout. This is the default and is used for direct integration with VS Code and GitHub Copilot CLI.\n\n```bash\n# Default - stdio transport\nbin/citus-mcp --coordinator_dsn \"postgres://...\"\n\n# Explicit\nbin/citus-mcp --transport stdio --coordinator_dsn \"postgres://...\"\n```\n\n**Use cases:**\n- VS Code Copilot Chat integration\n- GitHub Copilot CLI\n- Local development\n\n### 2. SSE Transport (Server-Sent Events)\n\nHTTP-based transport using Server-Sent Events. The server runs as an HTTP daemon that clients can connect to remotely.\n\n```bash\n# Start server on HTTP with SSE\nbin/citus-mcp --transport sse --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn \"postgres://...\"\n\n# Or via environment variables\nexport CITUS_MCP_TRANSPORT=sse\nexport CITUS_MCP_HTTP_ADDR=0.0.0.0\nexport CITUS_MCP_HTTP_PORT=8080\nexport CITUS_MCP_COORDINATOR_DSN=\"postgres://...\"\nbin/citus-mcp\n```\n\n**Endpoints:**\n- `GET /mcp` - Establish SSE connection\n- `POST /mcp/session/{id}` - Send messages to session\n- `GET /health` - Health check\n\n**Use cases:**\n- Remote MCP server deployment\n- Docker/Kubernetes deployments\n- Shared server for multiple clients\n- Network-accessible MCP services\n\n### 3. Streamable HTTP Transport\n\nModern HTTP transport with streaming support. Recommended for new deployments.\n\n```bash\n# Start server with streamable HTTP transport\nbin/citus-mcp --transport streamable --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn \"postgres://...\"\n```\n\n**Endpoints:**\n- `POST /mcp` - Handle MCP requests with streaming responses\n- `GET /health` - Health check\n\n**Use cases:**\n- Same as SSE, with better streaming support\n- Environments where SSE is not ideal\n\n### Docker Deployment Example\n\n```dockerfile\nFROM golang:1.22-alpine AS builder\nWORKDIR /app\nCOPY . .\nRUN go build -o citus-mcp ./cmd/citus-mcp\n\nFROM alpine:latest\nCOPY --from=builder /app/citus-mcp /usr/local/bin/\nEXPOSE 8080\nCMD [\"citus-mcp\", \"--transport\", \"sse\", \"--http-addr\", \"0.0.0.0\", \"--http-port\", \"8080\"]\n```\n\n```yaml\n# docker-compose.yml\nversion: '3.8'\nservices:\n  citus-mcp:\n    build: .\n    ports:\n      - \"8080:8080\"\n    environment:\n      CITUS_MCP_TRANSPORT: sse\n      CITUS_MCP_HTTP_ADDR: 0.0.0.0\n      CITUS_MCP_HTTP_PORT: 8080\n      CITUS_MCP_COORDINATOR_DSN: postgres://user:pass@citus-coordinator:5432/mydb?sslmode=disable\n```\n\n### Connecting to Remote Server\n\nFor SSE/Streamable transports, configure your MCP client to connect via HTTP:\n\n```json\n{\n  \"mcpServers\": {\n    \"citus-mcp\": {\n      \"type\": \"sse\",\n      \"url\": \"http://citus-mcp-server:8080/mcp\"\n    }\n  }\n}\n```\n\n---\n\n## 🔌 Setting Up with GitHub Copilot\n\n### VS Code Setup\n\n1. **Install Prerequisites**\n   - VS Code with GitHub Copilot extension\n   - MCP support enabled in Copilot settings\n\n2. **Create MCP Configuration**\n\n   Create `.vscode/mcp.json` in your workspace:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"citus-mcp\": {\n         \"command\": \"/absolute/path/to/bin/citus-mcp\",\n         \"args\": [],\n         \"env\": {\n           \"CITUS_MCP_COORDINATOR_DSN\": \"postgres://user:pass@localhost:5432/mydb?sslmode=disable\"\n         }\n       }\n     }\n   }\n   ```\n\n   Or for development (using `go run`):\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"citus-mcp\": {\n         \"command\": \"go\",\n         \"args\": [\"run\", \"./cmd/citus-mcp\"],\n         \"cwd\": \"/path/to/citus-mcp\",\n         \"env\": {\n           \"CITUS_MCP_COORDINATOR_DSN\": \"postgres://user:pass@localhost:5432/mydb?sslmode=disable\"\n         }\n       }\n     }\n   }\n   ```\n\n3. **Reload VS Code** and open Copilot Chat\n\n4. **Verify Connection**\n   ```\n   @citus-mcp ping\n   ```\n\n### GitHub Copilot CLI Setup\n\n1. **Create Global MCP Config**\n\n   Create `~/.config/github-copilot/mcp.json`:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"citus-mcp\": {\n         \"command\": \"/usr/local/bin/citus-mcp\",\n         \"args\": [],\n         \"env\": {\n           \"CITUS_MCP_COORDINATOR_DSN\": \"postgres://user:pass@localhost:5432/mydb?sslmode=disable\"\n         }\n       }\n     }\n   }\n   ```\n\n2. **Verify Setup**\n   ```bash\n   copilot mcp list\n   copilot mcp test citus-mcp\n   ```\n\n3. **Use in CLI**\n   ```bash\n   copilot -p \"Show me the cluster summary\"\n   ```\n\n---\n\n## 💡 Usage Examples\n\n### Basic Cluster Inspection\n\n```\n@citus-mcp Show me the cluster summary\n```\n\n```\n@citus-mcp List all distributed tables\n```\n\n```\n@citus-mcp Inspect the public.users table including shards and indexes\n```\n\n### Monitoring\n\n```\n@citus-mcp Show current cluster activity\n```\n\n```\n@citus-mcp Are there any lock waits in the cluster?\n```\n\n```\n@citus-mcp Show background job progress\n```\n\n### Analysis\n\n```\n@citus-mcp Analyze shard skew for the orders table\n```\n\n```\n@citus-mcp Show me the shard heatmap grouped by node\n```\n\n```\n@citus-mcp Explain this query: SELECT * FROM orders WHERE customer_id = 123\n```\n\n### Advisor\n\n```\n@citus-mcp Run the advisor with focus on skew\n```\n\n```\n@citus-mcp Check operational health (long queries, locks, jobs)\n```\n\n```\n@citus-mcp Suggest the best source node for snapshot-based scaling\n```\n\n```\n@citus-mcp Check metadata health with deep validation across nodes\n```\n\n### Configuration Analysis\n\n```\n@citus-mcp Analyze cluster configuration and recommend improvements\n```\n\n```\n@citus-mcp Run config advisor with focus on memory settings\n```\n\n### Colocation Analysis\n\n```\n@citus-mcp Show all colocation groups\n```\n\n```\n@citus-mcp Which tables are colocated with the orders table?\n```\n\n### Node Addition\n\n```\n@citus-mcp Run pre-flight checks for adding node at postgres://user:pass@newworker:5432/db\n```\n\n---\n\n## 📚 Tools Reference\n\n### Inspection Tools\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `ping` | `message?` | Health check |\n| `server_info` | — | Server metadata and mode |\n| `list_nodes` | `limit?`, `offset?` | Coordinator and workers |\n| `list_distributed_tables` | `limit?`, `offset?` | All distributed tables |\n| `list_shards` | `limit?`, `offset?` | Shards with placements |\n| `citus_cluster_summary` | `include_workers?`, `include_gucs?`, `include_config?` | Full cluster overview with config health |\n| `citus_list_distributed_tables` | `schema?`, `table_type?`, `limit?`, `cursor?` | Paginated table list |\n| `citus_list_reference_tables` | `schema?`, `limit?`, `cursor?` | Paginated reference table list |\n| `citus_table_inspector` | `table` (required), `include_shards?`, `include_indexes?` | Table deep dive |\n| `citus_colocation_inspector` | `colocation_id?`, `limit?` | Colocation groups |\n\n### Monitoring Tools\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `citus_activity` | `limit?`, `include_idle?`, `min_duration_secs?` | Active queries |\n| `citus_lock_inspector` | `include_locks?`, `limit?` | Lock waits |\n| `citus_job_inspector` | `state?`, `include_tasks?`, `limit?` | Background jobs |\n| `citus_shard_heatmap` | `table?`, `limit?`, `metric?`, `group_by?` | Hot shards |\n| `citus_shard_skew_report` | `table?`, `metric?`, `include_top_shards?` | Skew analysis |\n| `citus_explain_query` | `sql` (required), `analyze?`, `verbose?`, `costs?` | EXPLAIN query |\n\n### Advisor Tools\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `citus_advisor` | `focus?` (`skew`/`ops`), `max_tables?`, `include_next_steps?`, `include_sql_fixes?` | SRE advisor |\n| `citus_config_advisor` | `include_all_gucs?`, `category?`, `severity_filter?`, `total_ram_gb?` | Configuration analysis |\n| `citus_snapshot_source_advisor` | `strategy?`, `max_candidates?`, `include_simulation?` | Node addition advice |\n| `citus_validate_rebalance_prereqs` | `table` (required) | Rebalance readiness |\n| `citus_metadata_health` | `check_level?` (`basic`/`thorough`/`deep`), `include_fixes?` | Metadata consistency checks |\n| `citus_node_prepare_advisor` | `host` (required), `port?`, `database?`, `generate_script?` | Pre-flight node addition checks |\n\n### Execute Tools (Require Approval)\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `citus_rebalance_plan` | `table?`, `threshold?`, `max_shard_moves?`, `drain_only?` | Preview rebalance |\n| `citus_rebalance_execute` | `approval_token` (required), `table?`, `threshold?` | Start rebalance |\n| `citus_rebalance_status` | `verbose?`, `limit?`, `cursor?` | Rebalance progress |\n| `citus_move_shard_plan` | `shard_id`, `source_host`, `source_port`, `target_host`, `target_port`, `colocated?` | Preview move |\n| `citus_move_shard_execute` | `approval_token` (required), `shard_id`, `source_*`, `target_*`, `colocated?`, `drop_method?` | Execute move |\n| `citus_request_approval_token` | `action` (required), `ttl_seconds?` | Get approval token |\n| `rebalance_table_plan` | `table` (required) | Legacy: plan table rebalance |\n| `rebalance_table_execute` | `table` (required), `approval_token` (required) | Legacy: execute table rebalance |\n\n---\n\n## 📋 Built-in Prompts\n\nUse these prompts in Copilot Chat for guided workflows:\n\n| Prompt | Description |\n|--------|-------------|\n| `/citus.health_check` | Cluster health checklist |\n| `/citus.rebalance_workflow` | Step-by-step rebalance guide |\n| `/citus.skew_investigation` | Skew investigation playbook |\n| `/citus.ops_triage` | Operational triage workflow |\n\n---\n\n## 🔐 Security\n\n### Read-Only Mode (Default)\n\nBy default, citus-mcp runs in **read-only mode**. This means:\n- ✅ All inspection and monitoring tools work\n- ✅ Advisors provide recommendations\n- ❌ Execute operations are disabled\n- ❌ No data can be modified\n\n### Admin Mode with Approval Tokens\n\nTo enable execute operations:\n\n1. **Set admin mode** in configuration:\n   ```yaml\n   mode: admin\n   allow_execute: true\n   approval_secret: your-secret-key-here\n   ```\n\n2. **Request an approval token** before executing:\n   ```\n   @citus-mcp Request approval token for rebalance\n   ```\n\n3. **Use the token** in the execute command:\n   ```\n   @citus-mcp Execute rebalance with token: \u003ctoken\u003e\n   ```\n\nTokens are time-limited and action-specific (HMAC-signed).\n\n---\n\n## 🔧 Troubleshooting\n\n### Connection Issues\n\n**Error: `connection refused`**\n- Verify the coordinator host and port are correct\n- Check that PostgreSQL is running and accepting connections\n- Ensure firewall rules allow the connection\n\n**Error: `authentication failed`**\n- Verify username and password in DSN\n- Check that the user has permissions on the database\n- For SSL issues, try `sslmode=disable` for local testing\n\n### MCP Issues\n\n**Copilot doesn't see citus-mcp**\n- Ensure `mcp.json` is in the correct location\n- Check that the command path is absolute\n- Reload VS Code after changing configuration\n\n**Tools return errors**\n- Check logs: `CITUS_MCP_LOG_LEVEL=debug bin/citus-mcp`\n- Verify Citus extension is installed: `SELECT * FROM pg_extension WHERE extname = 'citus'`\n\n### Testing Connection\n\n```bash\n# Test directly\nCITUS_MCP_COORDINATOR_DSN=\"postgres://...\" bin/citus-mcp\n\n# Then send a ping via stdin\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | bin/citus-mcp\n```\n\n---\n\n## 🛠️ Development\n\n### Running Tests\n\n```bash\n# Unit tests\nmake test\n\n# With verbose output\ngo test -v ./...\n\n# Integration tests (requires Docker)\nmake docker-up\nmake integration\nmake docker-down\n```\n\n### Linting\n\n```bash\nmake lint\n```\n\n### Project Structure\n\n```\ncitus-mcp/\n├── cmd/citus-mcp/       # Main entry point\n├── internal/\n│   ├── mcpserver/       # MCP server implementation\n│   │   ├── tools/       # Tool implementations (30+ tools)\n│   │   ├── prompts/     # Prompt templates\n│   │   └── resources/   # Static resources\n│   ├── db/              # Database layer and worker management\n│   ├── citus/           # Citus-specific logic and queries\n│   │   ├── advisor/     # Advisor implementations\n│   │   └── guc/         # GUC (configuration) analysis\n│   ├── cache/           # Query result caching\n│   ├── config/          # Configuration management\n│   ├── errors/          # Error types and codes\n│   ├── fanout/          # Parallel query execution\n│   ├── logging/         # Structured logging\n│   └── safety/          # Guardrails and approval tokens\n├── docker/              # Docker Compose setup for testing\n├── docs/                # Additional documentation\n└── tests/               # Integration tests\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## 📄 License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⬆ Back to Top](#citus-mcp-server)**\n\nMade with ❤️ for the Citus community\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforall%2Fcitus-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeforall%2Fcitus-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforall%2Fcitus-mcp/lists"}