How to Get HDFS Capacity Reports Using `hdfs_dfadmin_report` in MCP Ambari API

The hdfs_dfadmin_report tool in the call518/mcp-ambari-api repository retrieves HDFS capacity metrics by querying the Ambari Metrics Service (AMS) and falling back to the Ambari REST API when necessary, formatting the output to match the native hdfs dfsadmin -report command.

The call518/mcp-ambari-api project provides a Model Context Protocol (MCP) server that exposes Hadoop cluster operations as callable tools. Among these, hdfs_dfadmin_report offers a programmatic way to monitor HDFS storage utilization without requiring direct shell access to NameNode hosts.

What Is hdfs_dfadmin_report?

hdfs_dfadmin_report is an MCP tool defined in src/mcp_ambari_api/mcp_main.py that simulates the output of the Hadoop command hdfs dfsadmin -report. Instead of executing shell commands on the cluster, the tool leverages the Ambari Metrics Service (AMS) to fetch live HDFS metrics and formats them into a human-readable report.

The tool accepts a single optional parameter:

• lookback_minutes (int): The time window in minutes to look back for metric values (default varies based on implementation).

How hdfs_dfadmin_report Works

The implementation follows a five-stage pipeline to ensure reliable data retrieval even when AMS is partially unavailable.

Step 1: AMS Availability Check

Before attempting metric collection, the tool calls check_ams_availability() from src/mcp_ambari_api/functions.py. If the Ambari Metrics Service is unreachable, the tool immediately returns a descriptive error message rather than failing silently.

# From mcp_main.py lines 50-52

if not check_ams_availability():
    return "Error: Ambari Metrics Service (AMS) is not available. Cannot retrieve HDFS metrics."

Step 2: Metric Collection from Ambari Metrics Service

When AMS is available, the tool constructs a mapping of critical HDFS metrics and fetches them concurrently using fetch_latest_metric_value. The specific metrics queried include:

• dfs.FSNamesystem.CapacityTotal
• dfs.FSNamesystem.CapacityUsed
• dfs.FSNamesystem.CapacityRemaining
• dfs.FSNamesystem.CapacityNonDFSUsed
• dfs.FSNamesystem.BlocksTotal
• dfs.FSNamesystem.UnderReplicatedBlocks
• dfs.FSNamesystem.CorruptBlocks
• dfs.FSNamesystem.MissingBlocks

This logic resides in src/mcp_ambari_api/mcp_main.py between lines 87-99.

Step 3: Fallback to Ambari REST API

If AMS returns null or unconfigured values for capacity metrics, the tool executes a fallback mechanism. It queries the Ambari REST endpoint /clusters/<cluster>/services/HDFS/components/NAMENODE using make_ambari_request and extracts equivalent metrics from the JSON response.

This fallback ensures that capacity reports remain available even during AMS outages or metric collection gaps, as implemented in lines 112-139 of mcp_main.py.

Step 4: Data Conversion and Formatting

Raw metric values (often in bytes) are converted to human-readable formats using helper functions:

• to_float: Safely converts string values to floats
• format_bytes: Transforms byte counts into TB, GB, or MB strings
• safe_percent: Calculates percentages without division-by-zero errors

These utilities appear in src/mcp_ambari_api/mcp_main.py lines 78-85.

Step 5: Report Assembly

Finally, the tool calculates derived values such as Present Capacity and DFS Used%, then assembles a multi-line text block that mirrors the classic hdfs dfsadmin -report output format. This formatted string is returned to the MCP client.

The report generation logic is located in lines 300-322 of mcp_main.py.

How to Call hdfs_dfadmin_report

The tool is exposed through the MCP server and can be invoked via multiple transport methods.

Using the MCP CLI (stdio mode)

Start the server in stdio mode and call the tool interactively:

# Start the server

PYTHONPATH=./src uv run python -m mcp_ambari_api

# In the interactive prompt, request the report

> hdfs_dfadmin_report(lookback_minutes=15)

Sample output:

Configured Capacity: 12.34 TB
Present Capacity:    11.80 TB
DFS Used%:           78.45%
DFS Remaining%:      21.55%
Non DFS Used:        4.20 GB (0.04%)
Under Replicated:    12
Corrupt Replicas:    0
Missing Blocks:      0

Using HTTP/Streamable HTTP Transport

Send a POST request to the MCP endpoint:

curl -X POST http://localhost:8000/mcp-ambari-api/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "tool": "hdfs_dfadmin_report",
        "args": { "lookback_minutes": 20 }
      }'

The response body contains the formatted report text.

Programmatic Python Invocation

Call the tool from another Python process using urllib:

import json
import urllib.request

payload = {
    "tool": "hdfs_dfadmin_report",
    "args": {"lookback_minutes": 10}
}
data = json.dumps(payload).encode()

req = urllib.request.Request(
    "http://localhost:8000/mcp-ambari-api/mcp",
    data=data,
    headers={"Content-Type": "application/json"},
    method="POST",
)

with urllib.request.urlopen(req) as resp:
    print(resp.read().decode())

Key Source Files and Implementation Details

Understanding the codebase structure helps when extending or debugging the tool:

File	Role	Key Functions
src/mcp_ambari_api/mcp_main.py	Tool declaration and report logic	hdfs_dfadmin_report(), to_float(), format_bytes(), safe_percent()
src/mcp_ambari_api/functions.py	AMS and Ambari REST utilities	check_ams_availability(), fetch_latest_metric_value(), make_ambari_request()
src/mcp_ambari_api/__main__.py	Server entry point	Starts stdio or HTTP transport
src/mcp_ambari_api/prompt_template.md	Natural language query examples	Documents example prompts that map to the tool

The tool specifically queries these HDFS metrics from AMS:

• dfs.FSNamesystem.CapacityTotal
• dfs.FSNamesystem.CapacityUsed
• dfs.FSNamesystem.CapacityRemaining
• dfs.FSNamesystem.CapacityNonDFSUsed

When AMS is unavailable, it falls back to the Ambari REST API endpoint /clusters/{cluster}/services/HDFS/components/NAMENODE.

Summary

• hdfs_dfadmin_report is an MCP tool in call518/mcp-ambari-api that retrieves HDFS capacity data without requiring shell access to Hadoop nodes.
• The tool prioritizes the Ambari Metrics Service (AMS) for real-time metrics but automatically falls back to the Ambari REST API if AMS is down or missing data.
• It calculates Present Capacity, DFS Used%, and Non-DFS Used from raw byte values, formatting them to match the classic hdfs dfsadmin -report output.
• You can invoke the tool via MCP stdio CLI, HTTP POST requests, or programmatically from Python applications.

Frequently Asked Questions

What metrics does hdfs_dfadmin_report return?

The tool returns a comprehensive capacity report including Configured Capacity, Present Capacity, DFS Used (percentage and bytes), DFS Remaining, Non DFS Used, and block health statistics such as Under Replicated Blocks, Corrupt Replicas, and Missing Blocks. These values mirror the output of the native Hadoop command hdfs dfsadmin -report.

Does hdfs_dfadmin_report require the Ambari Metrics Service to be running?

While the tool prefers to fetch data from the Ambari Metrics Service (AMS) for the most current values, it does not strictly require AMS to be available. If check_ams_availability() detects that AMS is down or if specific metrics return null, the tool automatically falls back to querying the Ambari REST API directly via make_ambari_request().

How does the tool format raw byte values into readable strings?

The tool uses helper functions defined in src/mcp_ambari_api/mcp_main.py to transform raw metric values. to_float() safely converts strings to floats, format_bytes() converts byte counts into human-readable units (TB, GB, MB), and safe_percent() calculates percentages while handling division-by-zero scenarios. These utilities ensure the final report is both accurate and readable.

Can I customize the time range for the metrics query?

Yes, the tool accepts a lookback_minutes parameter that specifies how far back to query for metric values. This parameter is passed to fetch_latest_metric_value when querying AMS, allowing you to retrieve capacity data from a specific time window rather than just the latest instantaneous value. If using the HTTP transport, include this parameter in the JSON payload's args object.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}