Citus MCP Server
An AI-powered MCP server for managing Citus distributed PostgreSQL clusters
Quick Start ⢠Features ⢠Installation ⢠Configuration ⢠Tools Reference ⢠Examples
š What is Citus MCP?
Citus MCP is a Model Context Protocol (MCP) server that enables AI assistants like GitHub Copilot to interact with your Citus distributed PostgreSQL cluster. It provides:
How It Works
āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā
ā GitHub Copilot ā MCP Protocol ā citus-mcp ā SQL ā Citus Cluster ā
ā (VS Code/CLI) ā <āāāāāāāāāāāāāāāāāā> ā server ā <āāāāāāāāāāāā> ā (Coordinator) ā
āāāāāāāāāāāāāāāāāāā stdio/SSE āāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā
š Quick Start
Prerequisites
- Go 1.23+ (for building from source)
- PostgreSQL 13ā17 with the Citus extension (11.x or later) on the coordinator
- GitHub Copilot with MCP support (VS Code or CLI)
1. Build the Server
git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp
make build
# Binary created at ./bin/citus-mcp
Or using Go directly:
go build -o bin/citus-mcp ./cmd/citus-mcp
2. Configure Your Connection
Create a configuration file at ~/.config/citus-mcp/config.yaml:
# Minimum required configuration
coordinator_dsn: postgres://username:password@localhost:5432/mydb?sslmode=disable
Or set the environment variable:
export CITUS_MCP_COORDINATOR_DSN="postgres://username:password@localhost:5432/mydb?sslmode=disable"
3. Set Up VS Code
Create .vscode/mcp.json in your workspace (or mcp.json at the project root):
{
"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. Test the Connection
In VS Code Copilot Chat, type:
@citus-mcp ping
You should see a "pong" response confirming the connection works.
⨠Features
71 MCP tools spanning diagnostics, forensics, capacity planning, advisors,
alarms, time-series, and gated execute operations. The single covering tool
citus_full_report runs ~30 read-only diagnostics in one shot and rolls
up overall health, top findings, and concrete recommendations.
See the full Tools Reference below for parameters and details.
š§ Reports & Covering Tools
š Cluster Inspection (Read-Only)
š Monitoring & Activity
š§ Memory & Capacity Planning
š ļø MX & Node Addition
š Forensics & Recovery
š§ Metadata, Extensions & Routing
š¤ Intelligent Advisors
šØ Alarms
š Time-Series & Snapshots
ā” Execute Operations (Approval Required)
š¦ Installation
Option 1: Build from Source
# Clone the repository
git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp
# Build using Make
make build
# Or build directly with Go
go build -o bin/citus-mcp ./cmd/citus-mcp
# (Optional) Install to your PATH
sudo cp bin/citus-mcp /usr/local/bin/
Option 2: Go Install
go install github.com/citusdata/citus-mcp/cmd/citus-mcp@latest
Verify Installation
citus-mcp --help
āļø Configuration
Connection String (DSN)
The most important configuration is the PostgreSQL connection string to your Citus coordinator:
postgres://[user]:[password]@[host]:[port]/[database]?sslmode=[mode]
Examples:
# Local development (no SSL)
postgres://postgres:secret@localhost:5432/mydb?sslmode=disable
# Production with SSL
postgres://admin:[email protected]:5432/production?sslmode=require
# With specific schema
postgres://user:pass@host:5432/db?sslmode=require&search_path=myschema
Configuration Methods
Configuration can be provided via (in order of precedence):
- Command-line flags
- Environment variables
- Configuration file
Method 1: Environment Variables
# Required
export CITUS_MCP_COORDINATOR_DSN="postgres://user:pass@localhost:5432/mydb?sslmode=disable"
# Optional
export CITUS_MCP_MODE="read_only" # read_only (default) or admin
export CITUS_MCP_ALLOW_EXECUTE="false" # Enable execute operations
export CITUS_MCP_APPROVAL_SECRET="secret" # Required if allow_execute=true
export CITUS_MCP_LOG_LEVEL="info" # debug, info, warn, error
Method 2: Configuration File
Create ~/.config/citus-mcp/config.yaml:
# ===========================================
# Citus MCP Server Configuration
# ===========================================
# Database Connection (REQUIRED)
# -----------------------------
coordinator_dsn: postgres://user:password@localhost:5432/mydb?sslmode=disable
# Optional: Override credentials from DSN
# coordinator_user: myuser
# coordinator_password: mypassword
# Connection Mode (RECOMMENDED: true for production)
# --------------------------------------------------
# When true (default), worker data is fetched via run_command_on_workers() UDF.
# Set to false only for dev/test with direct worker access.
coordinator_only: true
# Optional: Direct worker connections (dev/test override only)
# If specified when coordinator_only=true, these take precedence (dev escape hatch)
# worker_dsns: postgres://user:pass@worker1:5432/db,postgres://user:pass@worker2:5432/db
# Server Mode
# -----------
# read_only: Only inspection tools available (default, safest)
# admin: All tools available including execute operations
mode: read_only
# Execute Operations (only if mode=admin)
# ---------------------------------------
allow_execute: false
# approval_secret: your-secret-key # Required if allow_execute=true
# Performance Settings
# --------------------
cache_ttl_seconds: 5 # Cache duration for metadata queries
enable_caching: true # Set to false to disable caching
max_rows: 200 # Maximum rows returned per query
max_text_bytes: 200000 # Maximum text size in responses
# Timeouts
# --------
connect_timeout_seconds: 10 # Connection timeout
statement_timeout_ms: 30000 # Query timeout (30 seconds)
# Logging
# -------
log_level: info # debug, info, warn, error
# Transport (NEW)
# ---------------
# stdio: Standard input/output (default, for VS Code/CLI integration)
# sse: Server-Sent Events over HTTP (for remote/network access)
# streamable: Streamable HTTP transport (for remote/network access)
transport: stdio
# HTTP Settings (only used when transport is sse or streamable)
# http_addr: 127.0.0.1 # Listen address (use 0.0.0.0 for all interfaces)
# http_port: 8080 # Listen port
# http_path: /mcp # Endpoint path
# sse_keepalive_seconds: 30 # SSE keepalive interval
Method 3: Command-Line Flags
# Using flags (note: use underscores in flag names)
bin/citus-mcp --coordinator_dsn "postgres://..." --mode read_only
# Using positional argument for DSN
bin/citus-mcp "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
# Specify config file
bin/citus-mcp --config /path/to/config.yaml
# Start with SSE transport
bin/citus-mcp --transport sse --http_port 8080 --coordinator_dsn "postgres://..."
Configuration File Locations
The server searches for configuration files in this order:
--config/-cflagCITUS_MCP_CONFIGenvironment variable$XDG_CONFIG_HOME/citus-mcp/config.yaml~/.config/citus-mcp/config.yaml./citus-mcp.yaml(current directory)
Supported formats: YAML, JSON, TOML
š Transport Options
Citus MCP supports three transport modes for different deployment scenarios:
1. Stdio Transport (Default)
Standard 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.
# Default - stdio transport
bin/citus-mcp --coordinator_dsn "postgres://..."
# Explicit
bin/citus-mcp --transport stdio --coordinator_dsn "postgres://..."
Use cases:
- VS Code Copilot Chat integration
- GitHub Copilot CLI
- Local development
2. SSE Transport (Server-Sent Events)
HTTP-based transport using Server-Sent Events. The server runs as an HTTP daemon that clients can connect to remotely.
# Start server on HTTP with SSE
bin/citus-mcp --transport sse --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."
# Or via environment variables
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
Endpoints:
GET /mcp- Establish SSE connectionPOST /mcp/session/{id}- Send messages to sessionGET /health- Health check
Use cases:
- Remote MCP server deployment
- Docker/Kubernetes deployments
- Shared server for multiple clients
- Network-accessible MCP services
3. Streamable HTTP Transport
Modern HTTP transport with streaming support. Recommended for new deployments.
# Start server with streamable HTTP transport
bin/citus-mcp --transport streamable --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."
Endpoints:
POST /mcp- Handle MCP requests with streaming responsesGET /health- Health check
Use cases:
- Same as SSE, with better streaming support
- Environments where SSE is not ideal
Docker Deployment Example
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
Connecting to Remote Server
For SSE/Streamable transports, configure your MCP client to connect via HTTP:
{
"mcpServers": {
"citus-mcp": {
"type": "sse",
"url": "http://citus-mcp-server:8080/mcp"
}
}
}
š Setting Up with GitHub Copilot
VS Code Setup
-
Install Prerequisites
- VS Code with GitHub Copilot extension
- MCP support enabled in Copilot settings
-
Create MCP Configuration
Create
.vscode/mcp.jsonin your workspace:{ "mcpServers": { "citus-mcp": { "command": "/absolute/path/to/bin/citus-mcp", "args": [], "env": { "CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable" } } } }Or for development (using
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" } } } } -
Reload VS Code and open Copilot Chat
-
Verify Connection
@citus-mcp ping
GitHub Copilot CLI Setup
-
Create Global MCP Config
Create
~/.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" } } } } -
Verify Setup
copilot mcp list copilot mcp test citus-mcp -
Use in CLI
copilot -p "Show me the cluster summary"
š” Usage Examples
The examples below are natural-language prompts you can drop into Copilot Chat (VS Code / CLI). Copilot maps them to the underlying MCP tool call; JSON payloads are shown alongside where useful for automation.
Basic Cluster Inspection
@citus-mcp Give me everything about this cluster
ā citus_cluster_summary with {"all": true} ā returns coordinator/worker topology, counts, GUCs, configuration report, and the cross-tool health rollup (memory / connections / drift / metadata-sync / operational).
@citus-mcp List all distributed and reference tables
ā citus_list_distributed_tables, citus_list_reference_tables
@citus-mcp Inspect the public.orders table including shards and indexes
ā citus_table_inspector with {"table":"public.orders","include_shards":true,"include_indexes":true}
Monitoring
@citus-mcp Show current cluster activity
@citus-mcp Are there any lock waits right now?
@citus-mcp Show background job progress
@citus-mcp Proactive health dashboard for the cluster
ā citus_activity, citus_lock_inspector, citus_job_inspector, citus_proactive_health
Memory & Capacity Planning
@citus-mcp Project per-backend Citus metadata cache memory
ā citus_metadata_cache_footprint ā size of MetadataCacheMemoryContext per backend based on current shape.
@citus-mcp Estimate PG CacheMemoryContext footprint on the coordinator and each worker
ā citus_pg_cache_footprint ā relcache/catcache/plancache estimates.
@citus-mcp Is the cluster close to OOM? Use worst_case=true and 64 GiB per node
ā citus_memory_risk_report with {"worst_case":true, "node_ram_bytes":68719476736} ā 13-term budget (shared_buffers, wal_buffers, lock/pred-lock tables, WAL senders, logical decoding, bgworker baselines, per-backend process baseline + plan cache, Citus metadata + PG CacheMemoryContext, work_mem Ć hash_mem_multiplier Ć (1 + parallel_workers_per_gather) Ć plan_ops_per_query, temp_buffers, autovacuum, coordāworker libpq buffers) compared against node RAM.
@citus-mcp Sample PostgreSQL MemoryContextStats on every node
ā citus_worker_memcontexts ā live pg_get_backend_memory_contexts() fan-out across the cluster.
@citus-mcp What will happen to memory if I double the number of monthly partitions?
ā citus_partition_growth_simulator with {"partitions_per_parent":24}
@citus-mcp How many clients can each node handle? Compare coord-only, MX, and PgBouncer
ā citus_connection_capacity ā returns effective max client backends under each deployment mode plus bottleneck explanation.
@citus-mcp Simulate 400 concurrent multi-shard queries and tell me when max_shared_pool_size saturates
ā citus_connection_fanout_simulator with {"concurrent_clients":400}
@citus-mcp Should I use PgBouncer session or transaction mode with this workload?
ā citus_pooler_advisor
@citus-mcp Size hardware for 5Ć projected load: 50k IOPS, 2 TB data, 200 active clients
ā citus_hardware_sizer with {"projected_data_gb":2000,"projected_active_clients":200,"projected_iops":50000}
@citus-mcp Is 32 shards the right number? Chart the trade-offs
ā citus_shardcount_tradeoff_chart
MX & Node Addition
@citus-mcp Run pre-flight checks for adding a worker at newworker.prod:5432
ā citus_add_node_preflight with {"host":"newworker.prod","port":5432} ā coordinator-side checklist (extensions, types, schemas, roles, version match, max_locks_per_transaction/max_worker_processes/max_connections floors, wal_level=logical, replication slots).
@citus-mcp Advise how to prepare newworker.prod:5432 before I call citus_add_node and generate a shell script
ā citus_node_prepare_advisor with {"host":"newworker.prod","port":5432,"generate_script":true}
@citus-mcp Will metadata sync succeed on the new node, or should I use nontransactional mode? Target has 16 GiB RAM
ā citus_metadata_sync_risk with {"target_node_ram_gib":16} ā DDL count, locks-in-tx, duration, timeout correlations.
@citus-mcp Is the cluster ready for MX with 2 concurrent queries per peer and new nodes sized at max_connections=300?
ā citus_mx_readiness with {"concurrent_queries_per_peer":2,"new_node_max_connections":300,"expected_clients_per_node":100}
@citus-mcp Which existing worker should I snapshot from when adding a new one?
ā citus_snapshot_source_advisor
Metadata, Extensions & Routing
@citus-mcp Deep metadata consistency check across every node
ā citus_metadata_health with {"check_level":"deep","include_fixes":true}
@citus-mcp Are all extensions at the same version on every node?
ā citus_extension_drift_scanner
@citus-mcp Measure planner overhead across the cluster
ā citus_planner_overhead_probe
@citus-mcp Detect routing drift ā are any queries landing on the wrong shard?
ā citus_routing_drift_detector
@citus-mcp Run a synthetic probe to validate end-to-end correctness
ā citus_synthetic_probe
@citus-mcp Dump the session's active guardrails (statement timeout, read-only, row caps)
ā citus_session_guardrails
Advisors (Read-Only Recommendations)
@citus-mcp Run the Citus advisor focused on skew and include SQL fixes
ā citus_advisor with {"focus":"skew","include_sql_fixes":true}
@citus-mcp Analyze configuration, all categories, warn level and above
ā citus_config_advisor with {"severity_filter":"warning"}
@citus-mcp Deep inspection of PostgreSQL + Citus GUCs
ā citus_config_deep_inspect
@citus-mcp Advise on shard count per distributed table given current/projected load
ā citus_shard_advisor
@citus-mcp Which tables would benefit from columnar storage?
ā citus_columnar_advisor
@citus-mcp Show risky tenants (heavy shards, hot locks, outsized query share)
ā citus_tenant_risk
@citus-mcp Investigate which queries are pathological (cross-shard joins, broadcasts, repartitions)
ā citus_query_pathology
@citus-mcp Inspect the connected PgBouncer for pool health
ā citus_pgbouncer_inspector
Shard & Skew Analysis
@citus-mcp Skew report for the orders table by row count
@citus-mcp Heatmap of the hottest shards in the last interval
ā citus_shard_skew_report, citus_shard_heatmap
@citus-mcp Estimate the cost (time, WAL, bytes) of rebalancing the current cluster
ā citus_rebalance_cost_estimator
Time-Series / Snapshots
@citus-mcp Record a snapshot named pre-deploy-2026-04
@citus-mcp List snapshots taken in the last 30 days
@citus-mcp Trend query latency over the last 7 days
@citus-mcp Detect regressions against the pre-deploy-2026-04 snapshot
@citus-mcp Project 12-month growth from snapshots
@citus-mcp What changed between snapshots A and B?
ā citus_snapshot_record, citus_snapshot_list, citus_trend, citus_regression_detect, citus_growth_projection, citus_what_changed
Alarms
@citus-mcp List open alarms
@citus-mcp Acknowledge alarm abc-123
@citus-mcp Clear all resolved alarms older than 7 days
ā citus_alarms_list, citus_alarms_ack, citus_alarms_clear
Execute Operations (Approval Required)
@citus-mcp Plan a rebalance limited to 10 shard moves
@citus-mcp Request an approval token for rebalance
@citus-mcp Execute rebalance with token <token>
@citus-mcp Check rebalance status
ā citus_rebalance_plan ā citus_request_approval_token ā citus_rebalance_execute ā citus_rebalance_status
@citus-mcp Move shard 102008 from 10.0.0.5:5432 to 10.0.0.6:5432
ā citus_move_shard_plan + citus_move_shard_execute (with approval token)
@citus-mcp Isolate tenant 42 to its own shard
@citus-mcp Clean up orphaned shard placements left by a failed move
ā citus_isolate_tenant, citus_cleanup_orphaned
š Tools Reference
All tool names below can be invoked directly as MCP tool calls. Most
accept an optional object with the listed parameters; ā means the tool
takes no input.
š§ Reports & Covering Tools
Example ā citus_full_report:
// Default invocation: runs all read-only diagnostics with sensible defaults
{}
// With partition what-if and a tighter memory budget
{
"partition_growth_factor": 2.0,
"memory_budget_bytes": 4294967296
}
// Include optional synthetic probe + raw per-tool outputs (verbose)
{
"synthetic_probe": true,
"include_verbose_outputs": true
}
Core Inspection (read-only)
Monitoring & Activity
Memory & Capacity Planning
MX / Node Addition
Forensics & Recovery
Example ā citus_rebalance_forensics:
// Default: find most recent stuck/running job within last 24h
{}
// Diagnose a specific job, include finished tasks for postmortem
{"job_id": 42, "include_finished_tasks": true}
// Tighter thresholds: flag retries earlier, warn on smaller cleanup backlogs
{"retries_exhausted_threshold": 1, "cleanup_backlog_threshold": 10}
| citus_placement_integrity_check | schemas? (default ["public"]), skip_size_drift?, size_drift_factor? (default 2.0), max_rows_per_class? (default 200), check_inactive_placements? (default true) | Three-way cross-check between Citus metadata (pg_dist_placement Ć pg_dist_shard Ć pg_dist_node), on-disk reality on every worker (pg_class scan via run_command_on_workers with the Citus shard-visibility hook disabled), and pg_dist_cleanup. Detects: (a) ghost_placements ā metadata references shards missing on disk (reads WILL error); (b) orphan_tables ā shard-suffix tables on workers with no placement row (flagged whether or not queued in pg_dist_cleanup); (c) inactive_with_data ā shardstate != 1 but data still materialised; (d) size_drifts ā pg_relation_size vs placement.shardlength deviates > size_drift_factor; (e) stale_stats ā placement.shardlength = 0 but disk has data (silently causes rebalancer to make bad decisions; fix with SELECT citus_update_shard_statistics(shardid) or citus_update_table_statistics(relname)). Orphan classification matches on (base_name, shardid) pairs against metadata (not base name alone) so user tables like events_123456 with no matching shardid are not flagged. Trade-off: if a shard was fully removed (placement row gone, never queued for cleanup) but its on-disk table remains, it will not be detected as an orphan by the pair matcher ā use SELECT run_command_on_workers($$SELECT oid::regclass FROM pg_class WHERE relname ~ '_[0-9]+$'$$); as a belt-and-braces sweep for that case. Workers whose fanout fails are listed in skipped_workers[] with partial_results=true; ghost detection is suppressed for those nodes to avoid false-positive critical alarms. Emits a per-class reconciliation playbook (citus_copy_shard_placement / citus_cleanup_orphaned_resources / citus_update_shard_statistics) and alarms (placement.ghost, placement.orphan_tables, placement.inactive_with_data, placement.stale_stats, placement.partial_results). Read-only. |
Example ā citus_placement_integrity_check:
// Default ā scan public schema, detect all 4 classes
{}
// Multi-schema, skip size drift for speed
{"schemas": ["public", "tenants"], "skip_size_drift": true}
// Strict size drift (flag any > 1.5Ć deviation)
{"size_drift_factor": 1.5}
Example ā citus_2pc_recovery_inspector:
// Default ā detect commit_needed / rollback_needed / in_flight / foreign_initiator
{}
// Aggressive: treat anything >10s as orphan, escalate orphans older than 2 min
{"in_flight_threshold_seconds": 10, "stuck_orphan_seconds": 120}
// Compact output (no recovery script)
{"suppress_recovery_script": true}
// Include non-citus GIDs in the output (e.g. for third-party 2PC coordinators)
{"include_non_citus": true}
Metadata / Extensions / Routing
Advisors (read-only)
Alarms
Time-Series / Snapshots
Execute Operations (require approval token)
š Built-in Prompts
Use these prompts in Copilot Chat for guided workflows:
š Security
Read-Only Mode (Default)
By default, citus-mcp runs in read-only mode. This means:
- ā All inspection and monitoring tools work
- ā Advisors provide recommendations
- ā Execute operations are disabled
- ā No data can be modified
Admin Mode with Approval Tokens
To enable execute operations:
-
Set admin mode in configuration:
mode: admin allow_execute: true approval_secret: your-secret-key-here -
Request an approval token before executing:
@citus-mcp Request approval token for rebalance -
Use the token in the execute command:
@citus-mcp Execute rebalance with token: <token>
Tokens are time-limited and action-specific (HMAC-signed).
š§ Troubleshooting
Connection Issues
Error: connection refused
- Verify the coordinator host and port are correct
- Check that PostgreSQL is running and accepting connections
- Ensure firewall rules allow the connection
Error: authentication failed
- Verify username and password in DSN
- Check that the user has permissions on the database
- For SSL issues, try
sslmode=disablefor local testing
MCP Issues
Copilot doesn't see citus-mcp
- Ensure
mcp.jsonis in the correct location - Check that the command path is absolute
- Reload VS Code after changing configuration
Tools return errors
- Check logs:
CITUS_MCP_LOG_LEVEL=debug bin/citus-mcp - Verify Citus extension is installed:
SELECT * FROM pg_extension WHERE extname = 'citus'
Testing Connection
# Test directly
CITUS_MCP_COORDINATOR_DSN="postgres://..." bin/citus-mcp
# Then send a ping via stdin
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | bin/citus-mcp
š ļø Development
Running Tests
# Unit tests
make test
# With verbose output
go test -v ./...
# Integration tests (requires Docker)
make docker-up
make integration
make docker-down
Linting
make lint
Project Structure
citus-mcp/
āāā cmd/citus-mcp/ # Main entry point
āāā internal/
ā āāā mcpserver/ # MCP server implementation
ā ā āāā tools/ # Tool implementations (71 tools)
ā ā āāā prompts/ # Prompt templates
ā ā āāā resources/ # Static resources
ā āāā db/ # Database layer and worker management
ā āāā citus/ # Citus-specific logic and queries
ā ā āāā advisor/ # Advisor implementations
ā ā āāā guc/ # GUC (configuration) analysis
ā āāā cache/ # Query result caching
ā āāā config/ # Configuration management
ā āāā errors/ # Error types and codes
ā āāā fanout/ # Parallel query execution
ā āāā logging/ # Structured logging
ā āāā safety/ # Guardrails and approval tokens
āāā docker/ # Docker Compose setup for testing
āāā docs/ # Additional documentation
āāā tests/ # Integration tests
š¤ Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
š License
MIT License ā see LICENSE for details.
Made with ā¤ļø for the Citus community