Skip to main content
Glama

MCP-Ambari-API

copilot-instructions.md3.94 kB
# Copilot Instructions for MCP-Ambari-API ## Language Guidelines - **Code & Development**: Use English as the default language for all code, comments, documentation, and technical implementations unless explicitly requested otherwise by the user - **User Communication**: Use Korean as the default language for conversations and interactions with users through Copilot chat interface - **Documentation**: Technical documentation should be in English, while user-facing help and explanations should be in Korean ## Architecture & Transport Selection This MCP server supports dual transport modes with flexible configuration via CLI args and environment variables: - **stdio mode**: Default for local usage (`uvx mcp-ambari-api`) - **streamable-http mode**: For Docker/server deployment (`--type streamable-http` or `FASTMCP_TYPE=streamable-http`) **Priority**: CLI args > Environment vars > Defaults. The `main()` function in `src/mcp_ambari_api/mcp_main.py` (~2181 lines) handles transport selection and runs the FastMCP server. ## Core Patterns - **Tool Definition**: Every Ambari operation is an async function with `@mcp.tool()` + `@log_tool` decorators - **API Abstraction**: All Ambari REST calls go through `make_ambari_request()` in `functions.py` with automatic auth, error handling, and timing - **Environment Configuration**: Ambari connection via `AMBARI_HOST`, `AMBARI_PORT`, `AMBARI_USER`, `AMBARI_PASS`, `AMBARI_CLUSTER_NAME` env vars - **Unified Tool Pattern**: Modern tools like `dump_configurations` replace multiple specialized tools (superseded `get_configurations`, `list_configurations`) - **Error Handling**: Structured `{"error": "..."}` responses with HTTP status codes and timing info - **Logging**: The `@log_tool` decorator provides uniform timing, argument preview, and result categorization (SUCCESS/ERROR/EXCEPTION) ## Development Workflows - **Local Testing**: Use `run-mcp-inspector-local.sh` (not `scripts/`) with uv to test tools interactively - **Docker Development**: `docker-compose up -d` starts full stack (OpenWebUI + MCP server + MCPO proxy) - **Build & Deploy**: Version-specific Docker images via `build-mcp-server-docker-image.sh` and `build-mcpo-server-docker-image.sh` - **Package Structure**: Entry point is `mcp-ambari-api` console script → `mcp_ambari_api.mcp_main:main` - **Environment Setup**: Use `PYTHONPATH=./src` for local development, packaged resources in `mcp_ambari_api/prompt_template.md` ## Configuration Files - `mcp-config.json.stdio`: Local/command-line MCP client configuration - `mcp-config.json.http`: Docker-based MCP client configuration (uses streamable-http transport) - `docker-compose.yml` maps `mcp-config.json.http` into MCPO proxy container ## AI Agent Integration - **Canonical Prompt**: `src/mcp_ambari_api/prompt_template.md` contains the official system prompt with tool selection decision tree - **Safety-First**: Bulk operations (start/stop/restart all services) require explicit user intent - **Real Data Only**: AI agents must use tools for all cluster data—no guessing or hypothetical responses - **Tool Mapping**: Comprehensive table maps user intents/keywords to specific tools (e.g., "services" → `get_cluster_services`) ## Error Handling & Debugging - All tools return structured error responses with `{"error": "..."}` format - `@log_tool` decorator provides detailed timing and categorized results in logs - HTTP errors from Ambari API are captured and returned with status codes - Connection failures include timing information for debugging ## Key Files to Understand - `src/mcp_ambari_api/mcp_main.py`: Tool definitions, transport selection, main entrypoint - `src/mcp_ambari_api/functions.py`: `make_ambari_request()`, `@log_tool` decorator, formatting utilities - `src/mcp_ambari_api/prompt_template.md`: AI agent decision tree and tool selection guide - `docker-compose.yml`: Multi-container orchestration with environment mapping

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/call518/MCP-Ambari-API'

If you have feedback or need assistance with the MCP directory API, please join our Discord server