sample-cfm-tips-mcp/
├── playbooks/                            # CFM Tips optimization playbooks engine
│   ├── ec2/                             # EC2 optimization with 12 specialized tools
│   │   └── ec2_optimization.py          # EC2 right-sizing and comprehensive analysis
│   ├── ebs/                             # EBS volume optimization
│   │   └── ebs_optimization.py          # EBS volume optimization playbook
│   ├── rds/                             # RDS database optimization
│   │   ├── rds_optimization.py          # RDS database optimization playbook
│   │   └── database_savings_plans.py    # Database Savings Plans analysis
│   ├── aws_lambda/                      # Lambda function optimization
│   │   └── lambda_optimization.py       # Lambda function optimization playbook
│   ├── s3/                              # S3 storage optimization with 11 tools
│   │   └── s3_optimization_orchestrator.py # S3 cost optimization orchestrator
│   ├── cloudtrail/                      # CloudTrail optimization
│   │   └── cloudtrail_optimization.py   # CloudTrail optimization playbook
│   ├── cloudwatch/                      # CloudWatch optimization with 8 tools
│   │   └── cloudwatch_optimization.py   # CloudWatch cost optimization playbook
│   ├── nat_gateway/                     # NAT Gateway optimization
│   │   └── nat_gateway_optimization.py  # NAT Gateway optimization playbook
│   └── comprehensive_optimization.py    # Multi-service analysis
├── services/                             # AWS Services as datasources for the cost optimization
│   ├── s3_service.py                    # S3 API interactions and metrics
│   ├── s3_pricing.py                    # S3 pricing calculations and cost modeling
│   ├── cost_explorer.py                 # Cost Explorer API integration
│   ├── compute_optimizer.py             # Compute Optimizer API integration
│   └── optimization_hub.py              # Cost Optimization Hub integration
├── utils/                               # Cross-cutting utilities and analyzers
│   ├── analyzers/                       # Analysis engines for different optimization types
│   ├── logging_config.py                # Centralized logging configuration
│   ├── session_manager.py               # Session management for analysis results
│   └── parallel_executor.py             # Parallel execution utilities
├── mcp_server_with_runbooks.py           # Main MCP server with 50+ tools
├── runbook_functions.py                  # NAT Gateway and additional optimization functions
├── mcp_runbooks.json                     # Template file for MCP configuration file
├── requirements.txt                      # Python dependencies
├── tests/                               # Comprehensive test suite
├── diagnose_cost_optimization_hub_v2.py  # Diagnostic utilities
├── RUNBOOKS_GUIDE.md                     # Detailed usage guide
└── README.md                             # Project ReadMe

# Create a dedicated role for CFM Tips
aws iam create-role --role-name CFMTipsCostAnalysis --assume-role-policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::YOUR-ACCOUNT-ID:user/YOUR-USERNAME"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}'

# Attach the CFM Tips policies to the role
aws iam attach-role-policy --role-name CFMTipsCostAnalysis --policy-arn arn:aws:iam::YOUR-ACCOUNT-ID:policy/CFMTipsComprehensiveReadOnly

# Ensure CloudTrail is enabled for API monitoring
aws cloudtrail describe-trails --query 'trailList[*].[Name,IsLogging]'

# Create CloudTrail if not exists
aws cloudtrail create-trail --name cfm-tips-audit --s3-bucket-name your-cloudtrail-bucket
aws cloudtrail start-logging --name cfm-tips-audit

# Create AWS CLI profile for CFM Tips
aws configure --profile cfm-tips
export AWS_PROFILE=cfm-tips

# Test that no write operations are possible
aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::YOUR-ACCOUNT-ID:role/CFMTipsCostAnalysis \
  --action-names ec2:TerminateInstances s3:DeleteBucket rds:DeleteDBInstance \
  --resource-arns "*"
# Should return "implicitDeny" for all write operations

# Monitor CFM Tips API calls via CloudTrail
aws logs filter-log-events \
  --log-group-name CloudTrail/CFMTips \
  --start-time $(date -d '1 hour ago' +%s)000 \
  --filter-pattern "{ $.userIdentity.type = \"AssumedRole\" && $.userIdentity.arn = \"*CFMTipsCostAnalysis*\" }"

# Create VPC endpoints for AWS services (optional)
aws ec2 create-vpc-endpoint \
  --vpc-id vpc-12345678 \
  --service-name com.amazonaws.us-east-1.cost-optimization-hub \
  --route-table-ids rtb-12345678

# Required outbound HTTPS access to AWS APIs
# Allow outbound to: *.amazonaws.com on port 443
# No inbound connections required

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-east-1

# No credentials needed when running on EC2/ECS/Lambda with IAM role
# Role automatically provides temporary credentials

# ~/.aws/config
[profile cfm-tips-prod]
role_arn = arn:aws:iam::PROD-ACCOUNT:role/CFMTipsCostAnalysis
source_profile = default

[profile cfm-tips-dev]
role_arn = arn:aws:iam::DEV-ACCOUNT:role/CFMTipsCostAnalysis
source_profile = default

# For cross-account analysis, use cross-account roles
aws iam create-role --role-name CFMTipsCrossAccountRole --assume-role-policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::MANAGEMENT-ACCOUNT:role/CFMTipsCostAnalysis"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}'

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CostAnalysisServices",
      "Effect": "Allow",
      "Action": [
        "cost-optimization-hub:ListEnrollmentStatuses",
        "cost-optimization-hub:ListRecommendations",
        "cost-optimization-hub:GetRecommendation", 
        "cost-optimization-hub:ListRecommendationSummaries",
        "ce:GetCostAndUsage",
        "ce:GetCostForecast",
        "ce:GetUsageReport",
        "ce:GetCostCategories",
        "compute-optimizer:GetEC2InstanceRecommendations",
        "compute-optimizer:GetEBSVolumeRecommendations",
        "compute-optimizer:GetLambdaFunctionRecommendations",
        "compute-optimizer:GetAutoScalingGroupRecommendations",
        "compute-optimizer:GetECSServiceRecommendations",
        "support:DescribeTrustedAdvisorChecks",
        "support:DescribeTrustedAdvisorCheckResult",
        "pricing:GetProducts",
        "pricing:DescribeServices",
        "pricing:GetAttributeValues"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EC2AndNetworkAnalysis",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceTypes",
        "ec2:DescribeInstanceStatus",
        "ec2:DescribeVolumes",
        "ec2:DescribeSnapshots",
        "ec2:DescribeImages",
        "ec2:DescribeAddresses",
        "ec2:DescribeNatGateways",
        "ec2:DescribeRouteTables",
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeReservedInstances",
        "ec2:DescribeReservedInstancesOfferings",
        "ec2:DescribeCapacityReservations",
        "ec2:DescribeSpotInstanceRequests",
        "ec2:DescribeSpotPriceHistory",
        "ec2:GetEbsEncryptionByDefault",
        "ec2:GetEbsDefaultKmsKeyId"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "StorageAndDatabaseAnalysis",
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets",
        "s3:ListBucket",
        "s3:ListObjectsV2",
        "s3:GetBucketLocation",
        "s3:GetBucketVersioning",
        "s3:GetBucketLifecycleConfiguration",
        "s3:GetBucketNotification",
        "s3:GetBucketTagging",
        "s3:GetBucketPolicy",
        "s3:GetBucketAcl",
        "s3:GetBucketEncryption",
        "s3:ListMultipartUploads",
        "s3:GetStorageLensConfiguration",
        "s3:GetAnalyticsConfiguration",
        "s3:GetInventoryConfiguration",
        "rds:DescribeDBInstances",
        "rds:DescribeDBClusters",
        "rds:DescribeDBSnapshots",
        "rds:DescribeDBClusterSnapshots",
        "rds:DescribeReservedDBInstances",
        "rds:DescribeReservedDBInstancesOfferings",
        "pi:GetResourceMetrics",
        "pi:DescribeDimensionKeys",
        "pi:GetDimensionKeyDetails"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "LambdaAndMonitoringAnalysis",
      "Effect": "Allow",
      "Action": [
        "lambda:ListFunctions",
        "lambda:GetFunction",
        "lambda:GetFunctionConfiguration",
        "lambda:ListTags",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics",
        "cloudwatch:DescribeAlarms",
        "cloudwatch:DescribeAlarmsForMetric",
        "cloudwatch:GetDashboard",
        "cloudwatch:ListDashboards",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:DescribeMetricFilters",
        "logs:DescribeRetentionPolicy",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",
        "cloudtrail:GetEventSelectors",
        "cloudtrail:LookupEvents"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CFMTipsComprehensiveReadOnly",
      "Effect": "Allow",
      "Action": [
        "cost-optimization-hub:*",
        "ce:Get*",
        "ce:List*",
        "compute-optimizer:Get*",
        "support:DescribeTrustedAdvisor*",
        "pricing:*",
        "ec2:Describe*",
        "ec2:Get*",
        "s3:List*",
        "s3:Get*",
        "rds:Describe*",
        "lambda:List*",
        "lambda:Get*",
        "cloudwatch:Get*",
        "cloudwatch:List*",
        "cloudwatch:Describe*",
        "logs:Describe*",
        "pi:Get*",
        "pi:Describe*",
        "cloudtrail:Describe*",
        "cloudtrail:Get*",
        "cloudtrail:LookupEvents"
      ],
      "Resource": "*"
    }
  ]
}

# Core dependencies (automatically installed)
boto3>=1.28.0          # AWS SDK
botocore>=1.31.0        # AWS core library
mcp>=0.1.0              # Model Context Protocol
asyncio                 # Async support (built-in)
json                    # JSON handling (built-in)
logging                 # Logging (built-in)

# Clone the repository
git clone https://github.com/aws-samples/sample-cfm-tips-mcp.git
cd sample-cfm-tips-mcp

# Install dependencies
pip install -r requirements.txt

aws configure
# Enter your AWS Access Key ID, Secret Access Key, and default region

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

# No additional configuration needed if running on AWS compute with IAM role

python3 setup.py

# Start Kiro CLI chat
kiro-cli chat

# Example queries
"Show me cost optimization recommendations"
"Analyze my EC2 instances for right-sizing opportunities"

"Get my AWS costs for the last month"
"Show me cost optimization recommendations"
"What are my biggest cost drivers?"

"Find underutilized EC2 instances in us-east-1"
"Show me unused EBS volumes that I can delete"
"Identify idle RDS databases"
"Find unused Lambda functions"
"Analyze my S3 storage costs and recommend optimizations"
"Find incomplete multipart uploads in my S3 buckets"
"Recommend the best S3 storage class for my data"
"Identify stopped EC2 instances I can terminate"
"Find unattached Elastic IP addresses"
"Show me old generation instances that need upgrading"
"Identify instances compatible with Graviton processors"
"Find opportunities for EC2 Spot pricing"
"Analyze my NAT Gateway utilization and costs"
"Identify redundant NAT Gateways in my VPC"

"Analyze my CloudWatch spending and identify cost optimization opportunities"
"Find expensive custom metrics I can optimize"
"Optimize my CloudWatch log retention policies"
"Identify unused or inefficient CloudWatch alarms"
"Run comprehensive CloudWatch cost analysis"
"Show me CloudWatch cost estimates for different optimization scenarios"

"Analyze my database costs for Savings Plans opportunities"
"Model a $10/hour Database Savings Plans commitment"
"Review my existing Database Savings Plans utilization"
"Find cost optimization opportunities for Aurora and RDS instances"
"Analyze DynamoDB and ElastiCache costs for commitment plans"

"Generate a comprehensive cost optimization report"
"Create an EC2 right-sizing report in PDF format"
"Generate an EBS optimization report with cost savings"

"Run comprehensive cost analysis for all services in us-east-1"
"Analyze my AWS infrastructure for cost optimization opportunities"
"Show me immediate cost savings opportunities"
"Generate a comprehensive S3 optimization report"
"Analyze my S3 spending patterns and storage class efficiency"
"Run quick analysis to identify top cost optimization opportunities"
"Perform comprehensive CloudWatch optimization analysis"
"Analyze my network costs and NAT Gateway efficiency"
"Generate comprehensive EC2 optimization report covering all playbooks"

# Check Python version
python3 --version

# If Python 3.11+ not available, install via package manager
# macOS with Homebrew:
brew install python@3.11

# Ubuntu/Debian:
sudo apt update && sudo apt install python3.11 python3.11-venv

# CentOS/RHEL:
sudo yum install python3.11

# Upgrade pip first
python3 -m pip install --upgrade pip

# Install with verbose output for debugging
pip install -r requirements.txt -v

# If specific packages fail, install individually
pip install boto3 botocore mcp

# For M1/M2 Macs with architecture issues:
pip install --no-binary :all: boto3

# Verify AWS credentials are configured
aws sts get-caller-identity

# If credentials missing, configure them:
aws configure

# Or check environment variables:
echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY
echo $AWS_DEFAULT_REGION

# Check current region
aws configure get region

# Set region if not configured
aws configure set region us-east-1

# Or use environment variable
export AWS_DEFAULT_REGION=us-east-1

# Test specific permissions
aws cost-optimization-hub list-enrollment-statuses
aws ce get-cost-and-usage --time-period Start=2024-01-01,End=2024-01-02 --granularity MONTHLY --metrics BlendedCost

# Common permission error solutions:
# 1. Ensure IAM policies are attached to correct user/role
# 2. Wait 5-10 minutes for IAM changes to propagate
# 3. Check if Cost Optimization Hub is enabled in AWS Console

# Run diagnostic script
python3 diagnose_cost_optimization_hub_v2.py

# Enable Cost Optimization Hub in AWS Console:
# 1. Go to AWS Cost Management Console
# 2. Navigate to Cost Optimization Hub
# 3. Click "Get Started" and enable the service

# Verify CloudWatch is enabled and has data
aws cloudwatch list-metrics --namespace AWS/EC2

# Common issues:
# - Resources must run for 14+ days to have sufficient metrics
# - Detailed monitoring must be enabled for some metrics
# - Check correct region is being analyzed

# Test S3 permissions
aws s3 ls

# Common S3 issues:
# - Bucket policies may restrict access
# - Cross-region bucket access requires proper permissions
# - Large buckets may timeout - use bucket-specific analysis

# Verify Performance Insights is enabled
aws rds describe-db-instances --query 'DBInstances[*].[DBInstanceIdentifier,PerformanceInsightsEnabled]'

# Enable Performance Insights in RDS Console if needed

# Test MCP server directly
python3 mcp_server_with_runbooks.py

# Check MCP configuration file
cat ~/.kiro/settings/mcp.json

# Verify correct path in Kiro configuration
which python3
pwd  # Note full path to mcp_server_with_runbooks.py

# Verify Kiro CLI MCP configuration
cat ~/.kiro/settings/mcp.json
kiro-cli --version

# Reduce analysis scope
# - Specify specific regions instead of all regions
# - Use quick analysis tools for initial assessment
# - Analyze specific resources instead of comprehensive scans

# Increase timeouts for large accounts
export CFM_TIPS_TIMEOUT=600

# Reduce parallel threads if hitting API limits
export CFM_TIPS_MAX_THREADS=2

# AWS API throttling solutions:
# 1. Implement exponential backoff (built into boto3)
# 2. Reduce concurrent requests
# 3. Use pagination for large result sets
# 4. Consider AWS Support case for rate limit increases

# Check CloudTrail for throttling events
aws logs filter-log-events --log-group-name CloudTrail/APIGateway --filter-pattern "throttle"

# Solution: Configure AWS credentials
aws configure
# Or set environment variables as shown above

# Solution: Check IAM permissions
# 1. Verify policies are attached to correct user/role
# 2. Check policy syntax and permissions
# 3. Ensure services are enabled (Cost Optimization Hub, etc.)

# Solution: Check network connectivity and region
# 1. Verify internet connection
# 2. Check if region supports the service
# 3. Verify no proxy/firewall blocking AWS APIs

# Solution: Enable required AWS services
# 1. Cost Optimization Hub: Enable in AWS Console
# 2. Compute Optimizer: Opt-in via AWS Console
# 3. Trusted Advisor: Requires Business or Enterprise support plan

export CFM_TIPS_LOG_LEVEL=DEBUG
python3 mcp_server_with_runbooks.py

# Check log files
tail -f logs/cfm_tips_mcp.log
tail -f logs/cfm_tips_mcp_errors.log

# Comprehensive diagnostics
python3 diagnose_cost_optimization_hub_v2.py

# Test individual components
python3 -c "import boto3; print('Boto3 version:', boto3.__version__)"
python3 -c "from mcp.server import Server; print('MCP imported successfully')"

# Example usage with Add-on AWS Pricing MCP Server:
"Review the CDK by comparing it to the actual spend from my AWS account's stackset. Suggest cost optimization opportunities for the app accordingly"