# Terraform Plan Analyzer MCP Server

A Model Context Protocol (MCP) server that provides tools for analyzing Terraform plans. This server can execute terraform commands, analyze plan output, generate reports, and track log files.

## Features

- **Execute Terraform Commands**: Run terraform plan and other commands safely
- **Plan Analysis**: Parse terraform plan output and extract resource changes
- **Report Generation**: Create markdown reports with filtered results
- **Log File Tracking**: Keep track of generated log files
- **Configurable Filtering**: Filter out specific resource patterns (manifest versions, NAT VMs, etc.)
- **Environment Variable Support**: Execute commands with custom environment variables

## Installation

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Ensure you have terraform installed and available in your PATH

## Usage

### As an MCP Server

Run the server using stdio transport:
```bash
python server.py
```

The server will communicate using the Model Context Protocol over stdin/stdout.

### Available Tools

#### 1. `run_terraform_plan`
Execute a terraform plan command and return the output.

**Parameters:**
- `command` (optional): The terraform command to execute (default: "terraform plan")
- `working_directory` (optional): Directory to run the command in

**Example:**
```json
{
  "name": "run_terraform_plan",
  "arguments": {
    "command": "terraform plan -out=myplan.tfplan",
    "working_directory": "/path/to/terraform/project"
  }
}
```

#### 2. `analyze_terraform_output`
Analyze terraform plan output and extract changes.

**Parameters:**
- `plan_output`: The terraform plan output text to analyze
- `filter_patterns` (optional): List of patterns to filter out from results

**Example:**
```json
{
  "name": "analyze_terraform_output",
  "arguments": {
    "plan_output": "# terraform plan output here...",
    "filter_patterns": ["temp", "staging"]
  }
}
```

#### 3. `generate_plan_report`
Generate a comprehensive markdown report from terraform plan output.

**Parameters:**
- `plan_output`: The terraform plan output text to analyze
- `output_file` (optional): File path to save the report

**Example:**
```json
{
  "name": "generate_plan_report",
  "arguments": {
    "plan_output": "# terraform plan output here...",
    "output_file": "/path/to/report.md"
  }
}
```

#### 4. `run_custom_terraform_command`
Execute a custom terraform command with optional environment variables.

**Parameters:**
- `command`: The terraform command to execute
- `working_directory` (optional): Directory to run the command in
- `environment_vars` (optional): Environment variables to set

**Example:**
```json
{
  "name": "run_custom_terraform_command",
  "arguments": {
    "command": "terraform plan -var-file=staging.tfvars",
    "working_directory": "/path/to/project",
    "environment_vars": {
      "TF_WORKSPACE": "staging",
      "TF_LOG": "INFO"
    }
  }
}
```

## Configuration

### Filtering Patterns

By default, the analyzer filters out resources containing these patterns:
- `manifest`
- `version`
- `nat-vm`
- `nat_vm`

You can customize these patterns using the `filter_patterns` parameter in the `analyze_terraform_output` tool.

### Working Directory

If no working directory is specified, the server will use the current working directory where the server was started.

## Integration Examples

### With MCP Clients

The server follows the standard MCP protocol and can be integrated with any MCP-compatible client (Claude Desktop, GitHub Copilot CLI, etc.).

Example configuration:

```json
{
  "mcpServers": {
    "terraform-analyzer": {
      "command": "python",
      "args": ["/path/to/terraform-plan-mcp-server/server.py"],
      "cwd": "/path/to/your/terraform/project"
    }
  }
}
```

## Development

### Project Structure

```
terraform-plan-mcp-server/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── README.md              # This file
├── examples/              # Usage examples (optional)
└── tests/                 # Unit tests (optional)
```

### Key Components

1. **TerraformPlanAnalyzer**: Core class for terraform operations
2. **MCP Tools**: Decorated functions that implement the MCP tool interface
3. **Async Operations**: All terraform commands run asynchronously
4. **Logging**: Proper logging to stderr (not stdout) to avoid interfering with MCP protocol

### Error Handling

The server includes comprehensive error handling:
- Command execution errors are captured and returned
- Environment variable restoration after custom commands
- Proper cleanup of temporary files
- Logging of errors for debugging

## Security Considerations

- The server executes shell commands, so ensure it runs in a secure environment
- Environment variables are properly restored after custom commands
- Log files are created with appropriate permissions
- No sensitive data is logged or exposed

## Extending the Server

To add new tools:

1. Define a new function with the `@server.tool()` decorator
2. Include proper type hints and docstrings
3. Return `List[types.TextContent]` with the results
4. Handle errors appropriately and log them

Example:
```python
@server.tool()
async def my_custom_tool(param1: str, param2: Optional[int] = None) -> List[types.TextContent]:
    """
    Description of what this tool does.
    
    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2 (optional)
    """
    try:
        # Tool implementation here
        result = f"Processing {param1} with {param2}"
        return [types.TextContent(type="text", text=result)]
    except Exception as e:
        logger.error(f"Error in my_custom_tool: {e}")
        return [types.TextContent(type="text", text=f"Error: {str(e)}")]
```

## License

This project is provided as-is for educational and development purposes.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Support

For issues or questions:
1. Check the logs for error messages
2. Verify terraform is properly installed
3. Ensure working directory permissions are correct
4. Check MCP client configuration