Overview

The MCP (Model Context Protocol) server for Ambari provides a lightweight HTTP API to manage Hadoop clusters using Ambari while persisting operation state and metadata in PostgreSQL. It acts as an intermediary between orchestration systems and Ambari, recording service operations, configuration changes, and status updates in a durable store so you can audit, retry, and analyze cluster activity.

This approach is useful when you need reliable, observable control of Ambari-driven operations: long-running requests can survive restarts, failed actions can be retried from stored context, and downstream systems (analytics, dashboards, alerting) can query a single PostgreSQL-backed source of truth instead of polling Ambari directly.

Features

PostgreSQL-backed persistence for all Ambari service operations and requests
API for submitting, tracking, and querying service operations (start/stop/restart, config changes)
Configuration management with versioned change records and diff capability
Status monitoring endpoints to aggregate Ambari service health and node state
Request/state tracking with timestamps, statuses, and retry metadata
Lightweight HTTP interface suitable for orchestration integrations and automation

Installation / Configuration

You can run MCP server locally or in Docker. Below are common setup steps — adapt environment variables to your environment.

Clone the repository:

git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

Option A — Docker (recommended for quick start)

# Build image
docker build -t mcp-postgres-ops .

# Run (example)
docker run -d \
  -e DATABASE_URL=postgres://user:pass@db:5432/mcp \
  -e AMBARI_URL=https://ambari.example.com:8443 \
  -e AMBARI_USER=admin \
  -e AMBARI_PASS=secret \
  -p 8080:8080 \
  --name mcp-server \
  mcp-postgres-ops

Option B — Local (Python environment)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Configure environment
export DATABASE_URL='postgres://user:pass@localhost:5432/mcp'
export AMBARI_URL='https://ambari.example.com:8443'
export AMBARI_USER='admin'
export AMBARI_PASS='secret'

# Initialize DB (if migrations provided)
alembic upgrade head

# Start server
python run_server.py

Common environment variables (examples)

DATABASE_URL — PostgreSQL connection URL
AMBARI_URL — Ambari API base URL
AMBARI_USER / AMBARI_PASS — Ambari credentials or API key
SERVER_PORT — HTTP server port (default 8080)

Available Resources

API endpoints (examples)

POST /ops — Submit a new operation (start/stop/config-update)
GET /ops/:id — Get operation details and history
GET /services/:name/status — Retrieve aggregated status for a service
GET /requests — List recent requests with filters (status, service, time range)
POST /ops/:id/retry — Retry a failed operation

Example: submit a restart operation

curl -X POST http://localhost:8080/ops \
  -H "Content-Type: application/json" \
  -d '{
    "service": "HDFS",
    "action": "restart",
    "targets": ["nn1.example.com", "dn1.example.com"],
    "user": "automation"
  }'

Data model (core tables)

Table	Purpose
operations	Records each requested Ambari operation with status, start/end timestamps
requests	High-level user/submission records mapping to one or more operations
configs	Stored cluster configuration change records and metadata
statuses	Aggregated service/node status snapshots
retries	Retry metadata and counts for failed operations

Logs and metrics

Stores operation events to PostgreSQL for auditability
Exposes basic endpoints suitable for Prometheus scraping (if enabled)
Integrates with Ambari audit/logs to correlate system events

Use Cases

Auditable rolling restart

Submit a rolling restart for HDFS via POST /ops. Each host restart is tracked as an operation row in PostgreSQL. If the MCP process restarts mid-run, the server resumes tracking and continues retries based on stored context.

Zero-downtime config promotion

Push a new configuration to /configs, validate diff, and promote changes in controlled batches. Each change creates a versioned config row so you can rollback to the prior state if issues are detected.

Automated health monitoring and remediation

Schedule a job to call GET /services/HDFS/status; if the service is degraded, submit a remedial operation (e.g., restart failed components) and track it through the MCP API. Since all steps are persisted, you can analyze historical faults and remediation effectiveness.

External orchestration integration

Use MCP as the control-plane for higher-level orchestration tools (CI/CD, autoscalers). Instead of invoking Ambari directly, those tools post requests to MCP and consume operation states from the unified PostgreSQL store.

Notes and Best Practices

Secure the Ambari credentials and database access; use network-level controls and secrets management.
Back up PostgreSQL regularly to preserve operation history and audit logs.
Tune retry policies and timeouts for long-running Ambari operations to avoid duplicate side effects.
Consider enabling metrics/exporters if you want operational telemetry for MCP itself (request latency, queue depth, failure rates).

For the source code, issues, and contribution guidelines, see the project repository: https://github.com/call518/MCP-PostgreSQL-Ops.

MCP Server: PostgreSQL Ops for Ambari Integration