MCP-Ambari-API: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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. Built with FastMCP and aiohttp.

Development Commands

# Install dependencies (always use uv, never pip)
uv sync

# Run locally (stdio mode, for MCP Inspector)
PYTHONPATH=./src uv run python -m mcp_ambari_api

# Run locally (streamable-http mode)
PYTHONPATH=./src uv run python -m mcp_ambari_api --type streamable-http --host 0.0.0.0 --port 8000

# Run with .env config
source .env && PYTHONPATH=./src uv run python -m mcp_ambari_api --type ${FASTMCP_TYPE} --host ${FASTMCP_HOST} --port ${FASTMCP_PORT}

# MCP Inspector (interactive dev testing)
./run-mcp-inspector-local.sh

# Pre-commit (gitleaks secret scanning)
uv run pre-commit run --all-files

# Docker full stack (MCP server + MCPO proxy + OpenWebUI)
docker-compose up -d

# Build Docker images
./build-mcp-server-docker-image.sh
./build-mcpo-server-docker-image.sh

No tests or linting tools are currently configured.

Architecture

Two-module core design

• src/mcp_ambari_api/mcp_main.py (~3400 lines) — MCP tool/resource registration layer. Creates the FastMCP instance, decorates async functions with @mcp.tool() and @mcp.resource(), handles CLI argument parsing and server startup.
• src/mcp_ambari_api/functions.py (~1700 lines) — Business logic layer. HTTP request helpers (make_ambari_request, make_ambari_metrics_request), formatting utilities, metrics parsing/caching, and time-range resolution.

Transport modes

• stdio — Direct pipe with LLM clients (Claude Desktop, MCP Inspector). Default for local use.
• streamable-http — HTTP server exposing /mcp endpoint. Used for Docker deployment with MCPO proxy.

Docker stack flow

OpenWebUI (port 3001) → MCPO Proxy (port 8001) → MCP Server (port 18001) → Ambari REST API