3.7.3

[call518]

MCP Ambari API — v3.7.3 (First Release)

MCP Ambari API is a Model Context Protocol (MCP) server that bridges AI/LLM agents to Apache Ambari's REST API, enabling natural-language Hadoop cluster management. This is the first formal GitHub Release, consolidating all work since the initial commit.

---

Overview

This release provides a complete MCP server implementation that allows LLM clients (Claude Desktop, OpenWebUI, MCP Inspector, and any MCP-compatible client) to manage Hadoop clusters through conversational commands. The server communicates with Apache Ambari 2.7+ via its REST API and exposes the operations as MCP tools and resources.

---

Core Architecture

• Two-module design: mcp_main.py handles MCP tool and resource registration; functions.py contains business logic and HTTP helpers.
• Dual transport modes: stdio for direct LLM client integration and streamable-http for Docker-based deployments with MCPO proxy.
• Docker Compose stack: OpenWebUI → MCPO Proxy → MCP Server → Ambari REST API.
• Asynchronous HTTP: All Ambari API calls use aiohttp for non-blocking I/O.
• In-memory metrics caching: AMS metadata is cached with a configurable TTL to avoid redundant requests on large clusters.

---

Features

Cluster Management

• Retrieve cluster information and status.
• List and track active and running Ambari requests.
• Check the status and progress of specific request IDs.

Service Lifecycle

• Start, stop, and restart individual services (HDFS, YARN, Spark, HBase, and all other Ambari-managed services).
• Bulk operations: start, stop, or restart all cluster services simultaneously.

Configuration Management

• dump_configurations — unified tool replacing the former get_configurations and list_configurations tools.
  • Query a single configuration type (e.g., yarn-site, hdfs-site).
  • Bulk summary mode with optional service filter.
  • Key-only output (suppress values).
  • Substring filtering on type name or key name.

Host Management

• List all cluster hosts.
• Retrieve detailed host information including component states, hardware metrics, and service assignments.
• Start, stop, and restart individual host components.
• Detailed instance-level state breakdown per service component.

User Management

• List all Ambari users.
• Retrieve detailed user information including admin privileges, LDAP status, group memberships, and privileges.

Alert Management

• get_alerts_history — unified tool for both current and historical alerts.
  • Current mode: active alerts with real-time state, maintenance mode filtering, and summary formats.
  • History mode: time-range and pagination support for historical alert events.
  • State filtering: CRITICAL, WARNING, OK, UNKNOWN.
  • Definition-name filtering and multiple output formats (detailed, summary, compact).

Ambari Metrics Service (AMS) Integration

• Live metadata-backed metric catalog: metric names are discovered dynamically from /ws/v1/timeline/metrics/metadata instead of a hardcoded catalog.
• list_ambari_metric_apps — discover all AMS appId values with optional metric counts.
• list_common_metrics_catalog — keyword search against the live per-app metric catalog.
• list_ambari_metrics_metadata — raw AMS metadata explorer with app_id, metric_name_filter, host_filter, and search parameters.
• query_ambari_metrics — time-series data retrieval with exact-match metric names, host scoping, duration strings (e.g., 1h, 30m), and configurable precision.
• MCP resources exposed:
  • ambari-metrics://catalog/all
  • ambari-metrics://catalog/apps
  • ambari-metrics://catalog/<appId>
• AMS availability check performed before attempting any metrics retrieval.

HDFS Reporting

• hdfs_dfadmin_report — DFSAdmin-style capacity and DataNode summary that mirrors the output of hdfs dfsadmin -report, with async DataNode metric fetching.

Security and Authentication

• Optional Bearer token authentication for streamable-http mode via REMOTE_AUTH_ENABLE and REMOTE_SECRET_KEY environment variables or CLI flags.
• gitleaks secret scanning integrated as a pre-commit hook.

LLM Integration

• Prompt template (prompt_template.md) shipped inside the package for improved tool discoverability by LLM agents.
• Natural-language usage examples and parameter mapping included in tool docstrings.
• X-Requested-By header added to all Ambari API requests for protocol compatibility.

Observability

• log_tool decorator applied uniformly to all MCP tools for timing and structured logging.
• Configurable log level via the MCP_LOG_LEVEL environment variable.

---

Deployment

PyPI

uvx --python 3.12 mcp-ambari-api

Docker (streamable-http mode)

cp .env.example .env
# Edit .env with your Ambari cluster settings
docker-compose up -d

stdio (Claude Desktop / MCP Inspector)

{
  "mcpServers": {
    "mcp-ambari-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "your-ambari-host",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin",
        "AMBARI_PASS": "admin",
        "AMBARI_CLUSTER_NAME": "your-cluster"
      }
    }
  }
}

---

Dependencies

Package	Minimum Version	Shipped Version
fastmcp	2.12.3	3.2.0
aiohttp	3.12.15	3.13.4
Python	3.12	3.12

---

Requirements

• Apache Ambari 2.7 or later (earlier versions may work but are not officially tested).
• Python 3.12 or later.
• Docker and Docker Compose for the full-stack deployment.

---

Known Limitations

• No automated test suite is currently included. Tests are planned for a future release.

---

Links

• PyPI: https://pypi.org/project/mcp-ambari-api/
• Docker Hub: https://hub.docker.com/r/call518/mcp-server-ambari-api
• DeepWiki (architecture docs): https://deepwiki.com/call518/MCP-Ambari-API
• Ambari REST API reference: https://github.com/apache/ambari/blob/trunk/ambari-server/docs/api/v1/index.md

---

This discussion was created from the release 3.7.3.