# Cloud Custodian MCP

A Multi-Cloud Policy (MCP) generation and validation tool powered by Cloud Custodian and LLMs.

## Overview

Cloud Custodian MCP is an assistant for generating, validating, and managing Cloud Custodian policies across AWS, GCP, and Azure. It leverages natural language prompts to create YAML policies, supports approval workflows (Slack/Email), and provides a web UI for interaction and execution history.

## Demo

🎥 **[Watch an Interactive Demo](https://app.supademo.com/demo/cmcaj5ea91tjs8qsz4g18nonv)**

**CLI Interface Demo:**
![CLI Demo](custodian_cli_demo.gif)

**Web UI Demo:**
![UI Demo](custodian_ui_demo.gif)

## Core Features

- 🌐 **Multi-cloud support**: Generate policies for AWS, GCP, and Azure resources.
- 🤖 **Natural language to YAML**: Turn plain English requests into valid Cloud Custodian policies.
- 📝 **Policy explanation**: Ask for explanations of any policy YAML.
- 🖥️ **Web UI**: Chat interface for prompt/response and execution history.
- 🗃️ **Execution logging**: SQLite-backed logs of policy runs and results.

## Docker Setup

You can run both the UI and CLI versions of this application using Docker Compose. This is the recommended way to get started quickly and ensures all dependencies are handled for you.

### 1. Build the Docker Images

Build both the UI and CLI images with:
```bash
sudo docker compose build
```
This will create two separate images: one for the web UI and one for the CLI interface.

### 2. Run the CLI Interface

To start the CLI tool in an interactive shell, use:
```bash
sudo docker compose run cli
```
You will be dropped into a prompt where you can ask questions or generate policies, e.g.:
```
Ask me your Custodian related Questions (or 'exit'): how custodian can help me in cost reduction
...response...
Ask me your Custodian related Questions (or 'exit'): generate the policy for aws idle resources to stop ec2 instances having cpu utilization under 2 %
...YAML policy response...
```

### 3. Run the Web UI

To start the web UI, use:
```bash
sudo docker compose run ui
```
Then open [http://localhost:5000](http://localhost:5000) in your browser to access the application.

> **Note:** Make sure to configure your `.env` file with the required API keys and settings before building the images.

---

## Quick Start

### Using Docker (Recommended)

1.  **Ensure Docker is running:** Make sure Docker Desktop or your Docker daemon is active.
2.  **Create a `.env` file:** Copy `.env.sample` to `.env` and fill in your `GOOGLE_API_KEY`.
    ```bash
    cp .env.sample .env
    ```
3.  **Build and run the containers:**
    ```bash
    docker-compose up --build
    ```
4.  **Open the UI:** Visit [http://localhost:5000](http://localhost:5000) in your browser.

### Local Development (Poetry)

1. **Install dependencies:**
   ```bash
   poetry install
   ```
2. **Activate the virtual environment:**
    ```bash
    poetry shell
    ```
3. **Launch the Flask app:**
   ```bash
   python3 app.py
   ```
4. **Open the UI:**
   Visit [http://localhost:5000](http://localhost:5000) in your browser.

5. **Run CLI Interface (Alternative):**
   ```bash
   python cli.py
   ```
   
   **Sample CLI Interactions:**

   ### CLI Example 1: General Cost Reduction Question
   **Command:**
   ```bash
   how custodian can help me in cost reduction
   ```
   **Response:**
   ```
   Cloud Custodian can help with cost reduction in several ways by automating policy enforcement. It can identify and remove unused or idle resources, enforce tagging policies for better cost allocation and reporting, and right-size resources based on usage patterns. Do you have any specific scenarios in mind? For example, are you interested in finding idle EC2 instances or enforcing tagging compliance?
   ```

   ### CLI Example 2: Generate AWS Policy
   **Command:**
   ```bash
   generate the policy for aws idle resources to stop ec2 instances having cpu utilization under 2 %
   ```
   **Response:**
   ```yaml
   policies:
     - name: stop-idle-ec2-instances
       resource: aws.ec2
       filters:
         - type: metric
           name: CPUUtilization
           statistics: Average
           op: less-than
           value: 2
           period: 3600
         - StateName: running
       actions:
         - stop
   ```

   ### CLI Example 3: Dry Run a Policy
   **Command:**
   ```bash
   please dry run the policy for me
   ```
   **YAML Policy Input:**
   ```yaml
   policies:
     - name: stop-underutilized-instances
       resource: gcp.instance
       filters:
         - type: metrics
           name: compute.googleapis.com/instance/cpu/utilization
           op: lt
           value: 0.01
           days: 3
           aligner: ALIGN_MEAN
           reducer: REDUCE_MEAN
       actions:
         - type: stop
   ```
   **Response:**
   ```
   ╭───────────────────────────────────────────────────────────────────────────────────────────────────── Custodian MCP ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
   │ The dry run completed successfully.  It processed 0 resources and recommended 0 actions.  The policy stop-underutilized-instances for gcp.instance resources found no instances that met the criteria for stopping.     │
   ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
   ```

6. **Validate policies manually:**
   ```bash
   custodian validate policies/*.yml
   ```

## Sample Prompts & Responses

### 1. Generate a Policy
**Prompt:**
```
generate the policy for GCP to stop the instances having cpu utilization less than 3 percent
```
**Response:**
```yaml
policies:
  - name: stop-low-cpu-gce-instances
    resource: gcp.compute.instance
    filters:
      - type: metric
        metric: cpuUtilization.compute.googleapis.com/instance/cpu/utilization
        op: less-than
        value: 0.03
    actions:
      - type: stop
```

### 2. Explain the generated Policy
**Prompt:**
```
Explain this generated policy:
```
**Response:**
```
The generated policy searches for Google Compute Engine instances with CPU utilization less than 3% and stops them. Here's a breakdown:
* **`policies`**: This section defines a list of policies. In this case, there's only one.
* **`name: stop-low-cpu-gce-instances`**: This is the name of the policy. It's a descriptive name to help you identify it.
* **`resource: gcp.compute.instance`**: This specifies that the policy applies to Google Compute Engine instances.
* **`filters`**: This section defines the criteria for selecting instances.
* **`type: metric`**: This filter type checks against a specific metric.
* **`metric: cpuUtilization.compute.googleapis.com/instance/cpu/utilization`**: This is the specific metric being checked - CPU utilization for the instance.
* **`op: less-than`**: This specifies that the metric value should be less than the given value.
* **`value: 0.03`**: This is the threshold value. Instances with CPU utilization less than 0.03 (3%) will be selected.
* **`actions`**: This section defines what actions to take on the selected instances.
* **`type: stop`**: This action stops the selected instances.

This policy helps to save costs by stopping underutilized instances. Is there anything else I can help with?
```

### 3. List Available Policy Types
**Prompt:**
```
```

## Accessing Generated Policies

All policies generated by the tool (via UI or CLI) are automatically saved in the `cloud-custodian-mcp/generated` folder. You can directly access the YAML files in this directory—they are ready to execute with Cloud Custodian or to use in your CI/CD pipelines and automation workflows.

This makes it easy to review, edit, or deploy generated policies as needed.

---

## IDE Integration: Cursor & VSCode MCP Tools

You can enable this project as an interactive MCP tool in modern IDEs. See below for setup instructions for each IDE.

### Cursor

1. **Configuration:**
   - Add a `.cursor/mcp.json` file to your project root with the following content:
     ```json
     {
       "mcpServers": {
         "custodian-mcp": {
           "command": "poetry",
           "args": ["run", "python", "mcp_cursor_stdio.py"]
         }
       }
     }
     ```

2. **Restart Cursor:**
   - Fully close and reopen Cursor to detect the new MCP tool.

3. **Using the Tool:**
   - Open the MCP panel in Cursor (via the command palette or sidebar).
   - Select `custodian-mcp` and enter your prompt.

---

### VSCode (with MCP Extension)

1. **Configuration:**
   - If your VSCode setup supports MCP tools (via an extension or built-in), add a `.vscode/mcp.json` file to your project root.
     ```json
        {
        "servers": {
          "custodian-mcp": {
            "type": "stdio",
            "command": "poetry",
            "args": ["run", "python", "mcp_stdio.py"]
          }
        }
        }
     ```

2. **Restart VSCode:**
   - Fully close and reopen VSCode to detect the new MCP tool.

3. **Using the Tool:**
   - Open the MCP panel in VSCode (via the command palette or sidebar, depending on your extension).
   - Select `custodian-mcp-vscode` and enter your prompt.

---

## Configuration

The application is configured using environment variables. Create a `.env` file in the project root and add the following variables:

```
GOOGLE_API_KEY="your_google_api_key_here"
# Optional: for email notifications
EMAIL_SENDER="admin@example.com"
SMTP_HOST="localhost"
SMTP_PORT=25
# Optional: for Slack notifications
SLACK_WEBHOOK_URL="your_slack_webhook_url_here"
```

A `.env.sample` file is provided as a template.

## Architecture

The Cloud Custodian MCP application is designed with modularity and extensibility in mind. Key components include:

*   **Flask Web App (`app.py`):** Serves as the primary user interface, providing a chat-based interaction for policy generation and management. It exposes REST API endpoints for communication with the frontend and other services.
*   **CLI (`cli.py`):** Offers a command-line interface for direct interaction with the policy generation agent and for managing policies (listing, viewing, deleting, validating).
*   **Policy Generation Agent (`agent/mcp.py`):** The core intelligence of the application, leveraging a Language Model (LLM) to translate natural language prompts into Cloud Custodian YAML policies. It orchestrates the use of various tools.
*   **LLM Factory (`agent/llm_factory.py`):** Centralizes the instantiation of Language Models, allowing for easy swapping or integration of different LLM providers (e.g., Google Gemini, OpenAI, etc.).
*   **Tools (`agent/tools.py`):** A collection of functions exposed to the LLM agent, enabling it to perform specific actions like generating policies, explaining policies, listing policy types, and sending approval notifications.
*   **Configuration (`config.py`):** Manages application-wide settings and sensitive information (like API keys) securely through environment variables.
*   **Database (`db_init.py`):** Handles the initialization of the SQLite database used for storing execution history and policy approval requests.
*   **Approval Manager (`utils/approval_manager.py`):** Manages the lifecycle of policy approval requests, recording them in a database and providing an interface for tracking their status.
*   **Logging (`utils/logger.py`):** Provides a centralized and structured logging mechanism for the entire application, aiding in monitoring and debugging.
*   **Utility Modules (`utils/yaml_utils.py`, `utils/notifications.py`):** Contain helper functions for common tasks such as YAML processing and sending notifications (email/Slack).

## Contributing

Contributions are welcome! Please follow these steps:

1.  Fork the repository.
2.  Create a new branch for your feature or bug fix.
3.  Make your changes and ensure they adhere to the coding style.
4.  Write tests for your changes.
5.  Run the test suite to ensure all tests pass.
6.  Submit a pull request.

## License

This project is licensed under the [MIT License](LICENSE).

## Running Tests & Coverage

To run the test suite:
```bash
poetry run pytest
```

To check test coverage:
```bash
poetry run pytest --cov
```

Test files are located in the `tests/` directory. Please ensure all new features and bug fixes include appropriate tests.