# 代理设置指南
<a name="agent-setup-guide"></a>

GitHub 上的 [Agent Toolkit for Amazon](https://github.com/aws/agent-toolkit-for-aws) 提供了 `aws-core` 插件及其捆绑的 `aws-cloudformation` 技能。该技能可帮助 AI 编程代理创作和验证 CloudFormation 模板、排查部署故障以及生成 Amazon CDK 代码。该插件还配置 Amazon MCP 服务器以进行文档搜索和 Amazon API 访问。

## 与您的编码代理协作
<a name="agent-setup-work-with-agent"></a>

如需快速入门参考，您可以将此链接直接拖放到代理的上下文中：

```
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/agent-setup-guide.md
```

选择与您的开发环境相匹配的安装方法。

## 先决条件
<a name="agent-setup-prerequisites"></a>

确保满足以下先决条件：
+ [uv](https://docs.astral.sh/uv/) 已安装在您的系统上。
+ 系统上已安装 [Node.js](https://nodejs.org/) (v18\+)（这是技能安装的必要条件）。
+ （可选）在本地机器上配置了具有 IAM 凭证的 Amazon 账户。执行 Amazon API 调用（模板验证、部署故障排除）的工具需要凭证，但文档搜索则不需要。如果您没有配置凭证，请参阅[配置 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-configure.html)，以获取详细说明。

## 安装内容
<a name="agent-setup-what-gets-installed"></a>


| 组件 | 提供的功能 | 
| --- | --- | 
| aws-cloudformation 技能 | 采用安全默认设置的模板编写、三层验证管道（cfn-lint、cfn-guard、更改集），以及利用 CloudFormation 事件和 CloudTrail 关联分析对失败堆栈进行根本原因诊断。 | 
| Amazon IaC MCP 服务器 | 文档检索（CloudFormation 和 CDK）、模板验证、合规性检查、部署故障排除以及 CDK 最佳实操——所有这些操作均可在您的本地机器上运行。 | 

## Claude Code
<a name="agent-setup-claude-code"></a>

### 安装 `aws-core` 插件
<a name="agent-setup-claude-code-plugin"></a>

运行以下命令以从官方 Claude Code 市场安装该插件：

```
/plugin install aws-core@claude-plugins-official
```

这将一步安装 `aws-cloudformation` 技能、其他核心 Amazon 技能、代理挂钩和 Amazon MCP 服务器配置。

### 安装 Amazon IaC MCP 服务器
<a name="agent-setup-claude-code-mcp"></a>

将 `AWS_PROFILE` 替换为您的本地 Amazon 配置文件名称。

```
claude mcp add awslabs-aws-iac-mcp \
  -e AWS_PROFILE=default \
  -e AWS_REGION=us-east-1 \
  -e FASTMCP_LOG_LEVEL=ERROR \
  --scope user \
  -- uvx awslabs.aws-iac-mcp-server@latest
```

## Codex
<a name="agent-setup-codex"></a>

### 安装 CloudFormation 技能
<a name="agent-setup-codex-skill"></a>

```
npx skills add aws/agent-toolkit-for-aws/skills --skill aws-cloudformation --yes --global
```

### 安装 Amazon IaC MCP 服务器
<a name="agent-setup-codex-mcp"></a>

将 `AWS_PROFILE` 替换为您的本地 Amazon 配置文件名称。

```
codex mcp add awslabs-aws-iac-mcp \
  --env AWS_PROFILE=default \
  --env AWS_REGION=us-east-1 \
  --env FASTMCP_LOG_LEVEL=ERROR \
  -- uvx awslabs.aws-iac-mcp-server@latest
```

## Cursor
<a name="agent-setup-cursor"></a>

### 安装 CloudFormation 技能
<a name="agent-setup-cursor-skill"></a>

```
npx skills add aws/agent-toolkit-for-aws/skills --skill aws-cloudformation --yes --global
```

### 安装 Amazon IaC MCP 服务器
<a name="agent-setup-cursor-mcp"></a>

将以下内容添加到 `"mcpServers"` 内的 `.cursor/mcp.json` 中。将 `AWS_PROFILE` 替换为您的本地 Amazon 配置文件名称。

```
"awslabs.aws-iac-mcp": {
  "command": "uvx",
  "args": ["awslabs.aws-iac-mcp-server@latest"],
  "env": {
    "AWS_PROFILE": "default",
    "AWS_REGION": "us-east-1",
    "FASTMCP_LOG_LEVEL": "ERROR"
  }
}
```

## Kiro
<a name="agent-setup-kiro"></a>

### 在 Kiro CLI 中安装 CloudFormation 技能
<a name="agent-setup-kiro-skill"></a>

```
npx skills add aws/agent-toolkit-for-aws/skills --skill aws-cloudformation --yes --global
```

### 安装 Amazon IaC MCP 服务器
<a name="agent-setup-kiro-mcp"></a>

将以下内容添加到 `"mcpServers"` 内的 `~/.kiro/settings/mcp.json` 中。将 `AWS_PROFILE` 替换为您的本地 Amazon 配置文件名称。

```
"awslabs.aws-iac-mcp": {
  "command": "uvx",
  "args": ["awslabs.aws-iac-mcp-server@latest"],
  "env": {
    "AWS_PROFILE": "default",
    "AWS_REGION": "us-east-1",
    "FASTMCP_LOG_LEVEL": "ERROR"
  },
  "disabled": false
}
```

### 安装 Kiro powers（来自 Kiro IDE）
<a name="agent-setup-kiro-powers"></a>

安装以下 Kiro 能力包，它可按需为 Kiro 代理提供专用的 CloudFormation 上下文和工具：
+ **CloudFormation 和 CDK** - 通过 [Kiro 能力包链接](https://kiro.dev/powers/aws-iac)安装。

## GitHub Copilot
<a name="agent-setup-github-copilot"></a>

### 安装 CloudFormation 技能
<a name="agent-setup-github-copilot-skill"></a>

```
npx skills add aws/agent-toolkit-for-aws/skills --skill aws-cloudformation --yes --global
```

### 安装 Amazon IaC MCP 服务器
<a name="agent-setup-github-copilot-mcp"></a>

将以下内容添加到 `"mcpServers"` 内的 `.vscode/mcp.json` 中。将 `AWS_PROFILE` 替换为您的本地 Amazon 配置文件名称。

```
"awslabs.aws-iac-mcp": {
  "command": "uvx",
  "args": ["awslabs.aws-iac-mcp-server@latest"],
  "env": {
    "AWS_PROFILE": "default",
    "AWS_REGION": "us-east-1",
    "FASTMCP_LOG_LEVEL": "ERROR"
  }
}
```

## Windsurf
<a name="agent-setup-windsurf"></a>

### 安装 CloudFormation 技能
<a name="agent-setup-windsurf-skill"></a>

```
npx skills add aws/agent-toolkit-for-aws/skills --skill aws-cloudformation --yes --global
```

### 安装 Amazon IaC MCP 服务器
<a name="agent-setup-windsurf-mcp"></a>

将以下内容添加到 `"mcpServers"` 内的 `/.codeium/windsurf/mcp_config.json` 中。将 `AWS_PROFILE` 替换为您的本地 Amazon 配置文件名称。

```
"awslabs.aws-iac-mcp": {
  "command": "uvx",
  "args": ["awslabs.aws-iac-mcp-server@latest"],
  "env": {
    "AWS_PROFILE": "default",
    "AWS_REGION": "us-east-1",
    "FASTMCP_LOG_LEVEL": "ERROR"
  }
}
```

## OpenCode
<a name="agent-setup-opencode"></a>

### 安装 CloudFormation 技能
<a name="agent-setup-opencode-skill"></a>

```
npx skills add aws/agent-toolkit-for-aws/skills --skill aws-cloudformation --yes --global
```

### 安装 Amazon IaC MCP 服务器
<a name="agent-setup-opencode-mcp"></a>

将以下内容添加到 `"mcpServers"` 内的 `/.config/opencode/opencode.jsonc` 中。将 `AWS_PROFILE` 替换为您的本地 Amazon 配置文件名称。

```
"awslabs.aws-iac-mcp": {
  "command": "uvx",
  "args": ["awslabs.aws-iac-mcp-server@latest"],
  "env": {
    "AWS_PROFILE": "default",
    "AWS_REGION": "us-east-1",
    "FASTMCP_LOG_LEVEL": "ERROR"
  }
}
```

## 适用于与代理技能和 MCP 服务器配置兼容的所有其他代理
<a name="agent-setup-other-agents"></a>

对于任何其他支持开源代理技能格式和 MCP 服务器配置的代理，请按照以下步骤操作：

### 安装 CloudFormation 技能
<a name="agent-setup-other-agents-skill"></a>

```
npx skills add aws/agent-toolkit-for-aws/skills --skill aws-cloudformation --yes --global
```

### 安装 Amazon IaC MCP 服务器
<a name="agent-setup-other-agents-mcp"></a>

在 `"mcpServers"` 下的代理 MCP 客户端配置文件中添加 Amazon IaC MCP 服务器。将 `AWS_PROFILE` 替换为您的本地 Amazon 配置文件名称。

```
"awslabs.aws-iac-mcp": {
  "command": "uvx",
  "args": ["awslabs.aws-iac-mcp-server@latest"],
  "env": {
    "AWS_PROFILE": "default",
    "AWS_REGION": "us-east-1",
    "FASTMCP_LOG_LEVEL": "ERROR"
  }
}
```

## 代理可以为您做些什么
<a name="agent-setup-what-you-can-do"></a>

配置完成后，您的代理可以帮助您：


| 任务 | 提示示例 | 
| --- | --- | 
| 创建模板 | “为具有公有子网和私有子网的 VPC 创建 CloudFormation 模板” | 
| 部署前验证 | “验证位于 ./template.yaml 的模板并检查是否存在安全问题” | 
| 排查故障原因 | “我在 us-east-1 中的‘my-app’堆栈部署失败。发生了什么？” | 
| Search documentation (搜索文档) | “AWS::ECS::Service 支持哪些属性？” | 
| CDK 指南 | “给我介绍一下 Lambda 函数的 CDK 最佳实操” | 
| 合规性检查 | “检查我的模板是否符合安全最佳实操” | 

## IAM 权限
<a name="agent-setup-iam-permissions"></a>

MCP 服务器需要以下 Amazon 权限才能实现全部功能：

**对于模板验证和合规性：**无需 Amazon 权限（仅限本地验证）。

**对于部署故障排查：**

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudformation:DescribeStacks",
        "cloudformation:DescribeStackEvents",
        "cloudformation:DescribeStackResources",
        "cloudtrail:LookupEvents"
      ],
      "Resource": "*"
    }
  ]
}
```

## 相关资源
<a name="agent-setup-related-resources"></a>
+ [GitHub 上的 Amazon IaC MCP 服务器](https://github.com/awslabs/mcp/tree/main/src/aws-iac-mcp-server)
+ GitHub 上的 [Agent Toolkit for Amazon](https://github.com/aws/agent-toolkit-for-aws)
+ [CloudFormation 用户指南](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/)
+ [Amazon CDK 开发人员指南](https://docs.amazonaws.cn/cdk/v2/guide/)
+ [Amazon IaC MCP 服务器简介（博客）](https://www.amazonaws.cn/blogs/devops/introducing-the-aws-infrastructure-as-code-mcp-server-ai-powered-cdk-and-cloudformation-assistance/)