cloudagent-deploy/README.md

CloudAgent Deploy - MCP Server for CloudFormation deployments via backend API

# CloudAgent Deploy MCP Server

An MCP (Model Context Protocol) server for deploying CloudFormation infrastructure via backend API. This server eliminates the need for local AWS credentials by routing all CloudFormation operations through a secure backend API with cross-account role assumption.

## Features

- 🔐 **No Local AWS Credentials Required** - All operations use backend API with cross-account role assumption
- 🏗️ **Full CloudFormation Support** - Deploy, validate, delete, and monitor stacks
- ⚡ **Advanced Validation** - Security and compliance rules with property suggestions
- 📋 **Stack Management** - List stacks, get status, and track outputs
- 🎯 **Smart Detection** - Automatically detects CloudFormation templates in projects
- 🌐 **Static Site Support** - Handles both infrastructure and static deployments

## Installation

```bash
cd cloudagent-deploy
npm install
npm run build
```

## Configuration

### Environment Variables (Recommended)

```bash
export CLOUDAGENT_API_ENDPOINT="https://your-api-gateway-url.execute-api.region.amazonaws.com/prod"
export CLOUDAGENT_API_KEY="your-api-key-here"
export CLOUDAGENT_PROJECT_ROOT="/path/to/your/projects"  # Optional
```

### Configuration File

Create `.cloudagent-deploy.json` in your project directory:

```json
{
  "apiEndpoint": "https://your-api-gateway-url.execute-api.region.amazonaws.com/prod",
  "apiKey": "your-api-key-here",
  "projectRoot": "/path/to/your/projects"
}
```

## Usage

### MCP Tools Available

#### 1. `deploy`
Deploy a project to the cloud. Automatically detects CloudFormation templates and provides appropriate deployment options.

**Parameters:**
- `directory` (required): Full absolute path to project directory
- `outputDir` (optional): Relative path to build output directory
- `projectName` (optional): Name for the deployment

#### 2. `validate-infrastructure`
Validate CloudFormation templates against security and compliance rules.

**Parameters:**
- `template` (required): CloudFormation template content (YAML or JSON)
- `stackName` (required): Name for the CloudFormation stack

#### 3. `deploy-infrastructure`
Deploy CloudFormation templates via backend API.

**Parameters:**
- `template` (required): CloudFormation template content
- `stackName` (required): Name for the CloudFormation stack
- `parameters` (optional): Stack parameters
- `tags` (optional): Stack tags
- `capabilities` (optional): CloudFormation capabilities

#### 4. `delete-infrastructure`
Delete CloudFormation stacks.

**Parameters:**
- `stackName` (required): Name of stack to delete

#### 5. `get-stack-status`
Get status and outputs of CloudFormation stacks.

**Parameters:**
- `stackName` (required): Name of stack to check

#### 6. `list-stacks`
List all CloudFormation stacks.

**Parameters:** None

## Backend API Integration

This MCP server integrates with a backend CloudFormation API that provides:

- **Cross-Account Role Assumption**: No local AWS credentials needed
- **Advanced Validation**: Security rules and property suggestions
- **Stack Lifecycle Management**: Create, update, delete, monitor
- **User Authentication**: API key-based access control

### API Endpoints Used

- `POST /cfn/validate` - Validate CloudFormation templates
- `POST /cfn/deploy` - Deploy CloudFormation stacks
- `POST /cfn/delete` - Delete CloudFormation stacks
- `GET /cfn/status` - Get stack status and outputs
- `GET /cfn/list` - List user's stacks

## Security Features

- 🔐 **No Local Credentials**: All AWS operations via backend API
- 🛡️ **Role-Based Access**: Cross-account IAM role assumption
- 🔍 **Template Validation**: Security and compliance checks
- 📝 **Audit Trail**: All operations logged via backend
- 🎯 **Scoped Permissions**: Limited to CloudFormation operations

## Development

```bash
# Watch mode for development
npm run dev

# Build for production
npm run build

# Test the server
npm test
```

## Example Usage in Cursor

1. Configure your API endpoint and key
2. Open a project with CloudFormation templates
3. Use MCP tools to validate and deploy infrastructure
4. Monitor stack status and outputs
5. Delete stacks when no longer needed

## Troubleshooting

### Configuration Issues
- Ensure `CLOUDAGENT_API_ENDPOINT` and `CLOUDAGENT_API_KEY` are set
- Verify API endpoint URL is correct
- Check API key has valid permissions

### Validation Errors
- Review CloudFormation template syntax
- Address security and compliance warnings
- Use property suggestions from validation output

### Deployment Failures
- Check CloudFormation stack events in AWS console
- Verify IAM permissions for backend role
- Review template resource configurations

## Architecture

```
MCP Client (cloudagent-deploy) 
    ↓ HTTP/HTTPS
Backend API Gateway
    ↓ Lambda Invocation  
CloudFormation Lambda Function
    ↓ STS AssumeRole
User's AWS Account
    ↓ CloudFormation API
AWS Resources (S3, EC2, RDS, etc.)
```

This architecture ensures enterprise-grade security while providing a seamless deployment experience without local AWS credential management.