基于Amazon Quick与Amazon Bedrock AgentCore打造对话式 FinOps助手

export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

git clone https://github.com/sunl/billing-cost-management-mcp-server-for-amazon-quick.git

cd billing-cost-management-mcp-server-for-amazon-quick
python3.14 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
python awslabs/billing_cost_management_mcp_server/server.py

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

cat > trust-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "AssumeRolePolicy",
    "Effect": "Allow",
    "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {"aws:SourceAccount": "${AWS_ACCOUNT_ID}"},
      "ArnLike": {"aws:SourceArn": "arn:aws:bedrock-agentcore:${AWS_REGION}:${AWS_ACCOUNT_ID}:*"}
    }
  }]
}
EOF
aws iam create-role \
  --role-name BillingMCPServerAgentCoreRole \
  --assume-role-policy-document file://trust-policy.json \
  --description "AgentCore Runtime Role - Billing MCP Server"

cat > agentcore-base-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {"Sid": "ECRImageAccess", "Effect": "Allow", "Action": ["ecr:BatchGetImage","ecr:GetDownloadUrlForLayer"], "Resource": ["arn:aws:ecr:${AWS_REGION}:${AWS_ACCOUNT_ID}:repository/*"]},
    {"Sid": "ECRTokenAccess", "Effect": "Allow", "Action": ["ecr:GetAuthorizationToken"], "Resource": "*"},
    {"Sid": "LogsCreate", "Effect": "Allow", "Action": ["logs:DescribeLogStreams","logs:CreateLogGroup"], "Resource": ["arn:aws:logs:${AWS_REGION}:${AWS_ACCOUNT_ID}:log-group:/aws/bedrock-agentcore/runtimes/*"]},
    {"Sid": "LogsDescribe", "Effect": "Allow", "Action": ["logs:DescribeLogGroups"], "Resource": ["arn:aws:logs:${AWS_REGION}:${AWS_ACCOUNT_ID}:log-group:*"]},
    {"Sid": "LogsWrite", "Effect": "Allow", "Action": ["logs:CreateLogStream","logs:PutLogEvents"], "Resource": ["arn:aws:logs:${AWS_REGION}:${AWS_ACCOUNT_ID}:log-group:/aws/bedrock-agentcore/runtimes/*:log-stream:*"]},
    {"Sid": "XRay", "Effect": "Allow", "Action": ["xray:PutTraceSegments","xray:PutTelemetryRecords","xray:GetSamplingRules","xray:GetSamplingTargets"], "Resource": "*"},
    {"Sid": "Metrics", "Effect": "Allow", "Action": "cloudwatch:PutMetricData", "Resource": "*", "Condition": {"StringEquals": {"cloudwatch:namespace": "bedrock-agentcore"}}}
  ]
}
EOF
aws iam put-role-policy \
  --role-name BillingMCPServerAgentCoreRole \
  --policy-name AgentCoreBasePolicy \
  --policy-document file://agentcore-base-policy.json

cat > billing-mcp-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {"Sid": "CostExplorer", "Effect": "Allow", "Action": ["ce:GetCostAndUsage","ce:GetCostAndUsageWithResources","ce:GetCostAndUsageComparisons","ce:GetCostComparisonDrivers","ce:GetCostForecast","ce:GetUsageForecast","ce:GetDimensionValues","ce:GetTags","ce:GetCostCategories","ce:GetReservationPurchaseRecommendation","ce:GetReservationCoverage","ce:GetReservationUtilization","ce:GetSavingsPlansUtilization","ce:GetSavingsPlansCoverage","ce:GetSavingsPlansUtilizationDetails","ce:GetSavingsPlansPurchaseRecommendation","ce:GetAnomalies"], "Resource": "*"},
    {"Sid": "CostOptimizationHub", "Effect": "Allow", "Action": ["cost-optimization-hub:GetRecommendation","cost-optimization-hub:ListRecommendations","cost-optimization-hub:ListRecommendationSummaries"], "Resource": "*"},
    {"Sid": "ComputeOptimizer", "Effect": "Allow", "Action": ["compute-optimizer:GetAutoScalingGroupRecommendations","compute-optimizer:GetEBSVolumeRecommendations","compute-optimizer:GetEC2InstanceRecommendations","compute-optimizer:GetECSServiceRecommendations","compute-optimizer:GetRDSDatabaseRecommendations","compute-optimizer:GetLambdaFunctionRecommendations","compute-optimizer:GetEnrollmentStatus","compute-optimizer:GetIdleRecommendations"], "Resource": "*"},
    {"Sid": "Budgets", "Effect": "Allow", "Action": ["budgets:ViewBudget"], "Resource": "*"},
    {"Sid": "Pricing", "Effect": "Allow", "Action": ["pricing:DescribeServices","pricing:GetAttributeValues","pricing:GetProducts"], "Resource": "*"},
    {"Sid": "FreeTier", "Effect": "Allow", "Action": ["freetier:GetFreeTierUsage"], "Resource": "*"},
    {"Sid": "BCMPricingCalc", "Effect": "Allow", "Action": ["bcm-pricing-calculator:GetPreferences","bcm-pricing-calculator:GetWorkloadEstimate","bcm-pricing-calculator:ListWorkloadEstimateUsage","bcm-pricing-calculator:ListWorkloadEstimates"], "Resource": "*"},
    {"Sid": "BillingConductor", "Effect": "Allow", "Action": ["billingconductor:ListBillingGroups","billingconductor:ListBillingGroupCostReports","billingconductor:ListAccountAssociations","billingconductor:ListPricingPlans","billingconductor:ListPricingRules","billingconductor:ListPricingPlansAssociatedWithPricingRule","billingconductor:ListPricingRulesAssociatedToPricingPlan","billingconductor:ListCustomLineItems","billingconductor:ListCustomLineItemVersions","billingconductor:ListResourcesAssociatedToCustomLineItem"], "Resource": "*"}
  ]
}
EOF
aws iam put-role-policy \
  --role-name BillingMCPServerAgentCoreRole \
  --policy-name BillingMCPServerPolicy \
  --policy-document file://billing-mcp-policy.json
export EXECUTION_ROLE_ARN=$(aws iam get-role --role-name BillingMCPServerAgentCoreRole --query 'Role.Arn' --output text)
echo "Execution Role ARN: ${EXECUTION_ROLE_ARN}"

export POOL_NAME="<YOUR_POOL_NAME>"
export POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name "${POOL_NAME}" \
  --policies '{"PasswordPolicy":{"MinimumLength":8}}' \
  --region ${AWS_REGION} | jq -r '.UserPool.Id')
export CLIENT_ID=$(aws cognito-idp create-user-pool-client \
  --user-pool-id ${POOL_ID} \
  --client-name "BillingMCPClient" \
  --no-generate-secret \
  --explicit-auth-flows "ALLOW_USER_PASSWORD_AUTH" "ALLOW_REFRESH_TOKEN_AUTH" \
  --region ${AWS_REGION} | jq -r '.UserPoolClient.ClientId')
export COGNITO_USERNAME="<YOUR_USERNAME>"
export COGNITO_PASSWORD="<YOUR_SECURE_PASSWORD>"
aws cognito-idp admin-create-user \
  --user-pool-id ${POOL_ID} --username ${COGNITO_USERNAME} \
  --region ${AWS_REGION} --message-action SUPPRESS > /dev/null
aws cognito-idp admin-set-user-password \
  --user-pool-id ${POOL_ID} --username ${COGNITO_USERNAME} \
  --password ${COGNITO_PASSWORD} --region ${AWS_REGION} --permanent > /dev/null
export DISCOVERY_URL="https://cognito-idp.${AWS_REGION}.amazonaws.com/${POOL_ID}/.well-known/openid-configuration"
echo "Discovery URL: ${DISCOVERY_URL}"
echo "Client ID: ${CLIENT_ID}"

export COGNITO_DOMAIN_PREFIX="billing-mcp-$(echo ${AWS_ACCOUNT_ID} | tail -c 9)"
aws cognito-idp create-user-pool-domain \
  --user-pool-id ${POOL_ID} \
  --domain ${COGNITO_DOMAIN_PREFIX} \
  --region ${AWS_REGION}
echo "Cognito Domain: ${COGNITO_DOMAIN_PREFIX}"

aws cognito-idp create-resource-server \
  --user-pool-id ${POOL_ID} \
  --identifier "billing-mcp" \
  --name "Billing MCP Server" \
  --scopes '[{"ScopeName":"invoke","ScopeDescription":"Invoke Billing MCP Server"}]' \
  --region ${AWS_REGION}

QS_M2M_RESULT=$(aws cognito-idp create-user-pool-client \
  --user-pool-id ${POOL_ID} \
  --client-name "QuickM2MClient" \
  --generate-secret \
  --allowed-o-auth-flows "client_credentials" \
  --allowed-o-auth-scopes "billing-mcp/invoke" \
  --allowed-o-auth-flows-user-pool-client \
  --supported-identity-providers "COGNITO" \
  --region ${AWS_REGION})
export QS_M2M_CLIENT_ID=$(echo ${QS_M2M_RESULT} | jq -r '.UserPoolClient.ClientId')
export QS_M2M_CLIENT_SECRET=$(echo ${QS_M2M_RESULT} | jq -r '.UserPoolClient.ClientSecret')
echo "M2M Client ID: ${QS_M2M_CLIENT_ID}"
echo "M2M Client Secret: ${QS_M2M_CLIENT_SECRET}"

cat > cross-account-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "CrossAccountAssumeRole",
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": [
      "arn:aws:iam::<目标账号A>:role/BillingMCPCrossAccountRole",
      "arn:aws:iam::<目标账号B>:role/BillingMCPCrossAccountRole"
    ]
  }]
}
EOF
aws iam put-role-policy \
  --role-name BillingMCPServerAgentCoreRole \
  --policy-name CrossAccountAssumeRolePolicy \
  --policy-document file://cross-account-policy.json

agentcore create --project-name billing --name mcpserver --protocol MCP --build Container
cd billing

billing/
  AGENTS.md
  README.md
  agentcore/
    agentcore.json        # 项目和 agent 配置
    aws-targets.json      # AWS 账号和区域目标
    .env.local            # 本地环境变量（已 gitignore）
  app/
    mcpserver/
      Dockerfile
      README.md
      main.py             # 脚手架生成的入口文件（将被替换）
      pyproject.toml
      uv.lock

[
  {
    "name": "default",
    "account": "<粘贴 ${AWS_ACCOUNT_ID} 的实际值>",
    "region": "us-east-1"
  }
]

agentcore deploy --dry-run --yes

agentcore deploy -y

agentcore status

export AGENT_ARN="<上述输出中的 Agent ARN>"

export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
  --client-id "${CLIENT_ID}" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=${COGNITO_USERNAME},PASSWORD=${COGNITO_PASSWORD} \
  --region ${AWS_REGION} | jq -r '.AuthenticationResult.AccessToken')
ENCODED_ARN=$(echo -n ${AGENT_ARN} | jq -sRr '@uri')
MCP_ENDPOINT="https://bedrock-agentcore.${AWS_REGION}.amazonaws.com/runtimes/${ENCODED_ARN}/invocations?qualifier=DEFAULT"
curl -X POST "${MCP_ENDPOINT}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ${BEARER_TOKEN}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

ENCODED_ARN=$(echo -n ${AGENT_ARN} | jq -sRr '@uri')
MCP_SERVER_ENDPOINT="https://bedrock-agentcore.${AWS_REGION}.amazonaws.com/runtimes/${ENCODED_ARN}/invocations"
TOKEN_URL="https://${COGNITO_DOMAIN_PREFIX}.auth.${AWS_REGION}.amazoncognito.com/oauth2/token"
echo "MCP Server 端点: ${MCP_SERVER_ENDPOINT}"
echo "Client ID:       ${QS_M2M_CLIENT_ID}"
echo "Client Secret:   ${QS_M2M_CLIENT_SECRET}"
echo "Token URL:       ${TOKEN_URL}"

You are an AWS Cost Analysis Expert with deep expertise in AWS Billing and Cost Management. Your purpose is to help users understand their AWS spending patterns, identify cost optimization opportunities, and provide actionable recommendations. When presenting cost data, always organize information clearly with breakdowns by service, time period, and usage patterns. Highlight unusual spending spikes or trends that warrant attention. When providing optimization recommendations, explain the potential savings, implementation complexity, and any trade-offs. Use clear visualizations and summaries to make complex billing data accessible and actionable.
Cross-Account Query Considerations:
When target_account_id is specified:
- Do NOT use LINKED_ACCOUNT dimension to filter the same account ID
- The target_account_id parameter already scopes the query to that specific account
- Adding a LINKED_ACCOUNT filter for the same account will return empty results if that account is the management/payer account (management accounts do not appear in the LINKED_ACCOUNT dimension)

agentcore remove all
agentcore deploy -y

aws cognito-idp delete-user-pool-domain \
  --user-pool-id ${POOL_ID} --domain ${COGNITO_DOMAIN_PREFIX} --region ${AWS_REGION}
aws cognito-idp delete-user-pool --user-pool-id ${POOL_ID} --region ${AWS_REGION}

for P in AgentCoreBasePolicy BillingMCPServerPolicy CrossAccountAssumeRolePolicy; do
  aws iam delete-role-policy --role-name BillingMCPServerAgentCoreRole --policy-name $P 2>/dev/null || true
done
aws iam delete-role --role-name BillingMCPServerAgentCoreRole

AWS Cost Analysis Specialist Agent
Core Identity
You are an AWS Cost Analysis Specialist with deep expertise in AWS Billing and Cost Management. Your purpose is to help users understand their AWS spending patterns, identify cost drivers, and provide actionable optimization recommendations.
Cost Data Presentation Standards
When presenting cost data, you MUST:
1.Organize information clearly with specific dollar amounts, time periods, and service breakdowns
2.Preserve original precision - Display cost data exactly as returned by the API without rounding
3.Proactively highlight unusual spending patterns, cost spikes, or optimization opportunities
4.Use visualizations and comparisons to make cost data easy to understand
Cost Data Query Principles
1. Complete Data First (Default Behavior)
ALWAYS retrieve complete data for all services by default when users request cost or billing information.
Do NOT proactively add filters for SERVICE, LINKED_ACCOUNT, or other dimensions to narrow the query scope unless explicitly requested.
Add filters ONLY when the user explicitly specifies:
• Service names (e.g., "show me EC2 costs")
• Account scope (e.g., "costs for account {US_BANK_ACCOUNT_NUMBER}")
• Region constraints (e.g., "us-east-1 spending")
• Tag filters (e.g., "costs tagged as Production")
• Any other specific filtering criteria
Query Behavior Examples:
User RequestCorrect BehaviorIncorrect Behavior"Show me last month's costs"No filters; group by SERVICE and return all service costs❌ Adding SERVICE filter to limit scope"Analyze my costs"Return complete data across all services❌ Guessing which services matter"Show me EC2 and S3 costs"Add SERVICE filter limited to EC2 and S3❌ Returning all services"What did I spend on Lambda?"Add SERVICE filter for AWS Lambda only❌ Including other services
2. Preserve Numerical Precision
ALWAYS display cost amounts with the original precision returned by the API. Do NOT round, truncate, or modify monetary values. Accuracy in financial data is critical.
3. Cross-Account Query Considerations
When target_account_id is specified:
• Do NOT use LINKED_ACCOUNT dimension to filter the same account ID
• The target_account_id parameter already scopes the query to that specific account
• Adding a LINKED_ACCOUNT filter for the same account will return empty results if that account is the management/payer account (management accounts do not appear in the LINKED_ACCOUNT dimension)
4. Retrieve Aggregate Billing Data from API
For annual or monthly billing totals, ALWAYS retrieve data directly from the API. Do NOT calculate totals by summing individual service costs.
Recommendation Guidelines
When providing cost optimization recommendations, you MUST:
1.Explain the potential savings impact - Quantify expected cost reductions when possible
2.Assess implementation complexity - Indicate whether the change is simple, moderate, or complex
3.Provide actionable next steps - Give users clear guidance on how to implement recommendations
4.Prioritize high-impact, low-effort optimizations - Help users achieve quick wins
Communication Standards
• Tone: Professional, analytical, and helpful. Use clear explanations when discussing financial data.
• Response Length: Provide comprehensive analysis with sufficient detail to be actionable, but remain concise and focused on key insights. Avoid unnecessary verbosity.
• Clarity: Break down complex cost structures into understandable components. Use examples and comparisons to illustrate points.
• Output Style: Always provide a summary overview first, followed by detailed data. Use charts or structured formats to present cost breakdowns. Highlight key insights and anomalies.
• Language Flexibility: Respond in the user's preferred language. If the user communicates in Chinese, provide responses in Chinese while maintaining the same analytical rigor and structure.