setup-devops-agent

AWS DevOps Agent — Claude 设置

以下说明专门用于在 Claude 应用中设置 AWS DevOps Agent 插件。对于其他客户端，可将这些说明作为参考，但请根据客户端的具体要求进行调整。

步骤 0：检查是否需要设置

1/ 检查“aws-devops-agent” MCP 服务是否正在运行。如果正在运行，请验证连接是否有效（参见“步骤 3：验证连接”）。

如果验证成功，应告知用户插件已使用 SigV4 or Bearer Token 完成设置。询问用户是否希望将配置切换为 Bearer Token or SigV4，详情请参见下文“步骤 2：选择身份验证方式”。

如果用户不想更改身份验证配置，则设置已完成，请在此处停止。

2/ 检查以下位置中是否存在键为“aws-devops-agent”的 MCP 服务配置：

• 插件范围：${CLAUDE_PLUGIN_ROOT}/.mcp.json
• 项目范围：.mcp.json（位于项目目录中，由版本控制）
• 项目特定：.claude/settings.local.json（位于项目目录中）
• 用户本地配置：~/.claude/settings.local.json
• 用户全局配置：~/.claude/settings.json
• 主 Claude.json：~/.claude.json
• 专用 MCP 文件：~/.claude/mcp_servers.json

然后：

• 如果 aws-devops-agent 键存在，且服务已连接（工具可用，参见“步骤 3：验证连接”）→ 告知用户：“DevOps Agent 已完成配置并已连接。”如果 MCP 配置使用 Bearer Token，建议也可以为 AWS DevOps Agent 插件设置 SigV4 凭证（支持多个 Agent 空间和管理工具）。如果 MCP 配置使用 SigV4 凭证，建议也可以为 AWS DevOps Agent 插件设置 Bearer Token 凭证（适用于单个 Agent 空间）。
• 如果 aws-devops-agent 键存在但连接失败 → 继续“步骤 1：诊断当前状态”
• 如果不存在 aws-devops-agent 键 → 继续“步骤 1：诊断当前状态”

---

步骤 1：诊断当前状态

运行以下检查：

# Bearer token
echo "DEVOPS_AGENT_TOKEN: $([ -n "$DEVOPS_AGENT_TOKEN" ] && echo 'set' || echo 'not set')"
echo "DEVOPS_AGENT_REGION: ${DEVOPS_AGENT_REGION:-not set}"

# SigV4 dependencies
uvx --version 2>&1

# AWS credentials
aws sts get-caller-identity 2>&1

确定：

• bearer_ready = 已设置 DEVOPS_AGENT_TOKEN 且已设置 DEVOPS_AGENT_REGION
• sigv4_ready = aws sts get-caller-identity 执行成功且已安装 uvx

---

步骤 2：选择身份验证方式

完成诊断后，始终询问用户想选择哪种方式——即使只有一种方式可用。说明检查结果，让用户自行选择。

如果用户只能访问 Agent 空间的运维应用，可能会想使用承载令牌。

如果用户使用多个 Agent 空间和／或拥有管理 Agent 空间的管理员权限，可能会想使用 SigV4。

承载令牌已就绪	SigV4 已就绪	操作
是	是	“您已配置承载令牌和 AWS 凭证。您希望 DevOps Agent 使用哪种方式？承载令牌（单个 Agent 空间）还是 AWS 凭证 / SigV4（多个 Agent 空间和管理员工具）？”
是	否	“您已配置承载令牌。要我使用您的承载令牌（单个 Agent 空间）为您设置 DevOps Agent 吗？还是您更想改为配置 AWS 凭证 / SigV4（多个 Agent 空间和管理员工具）？”
否	是	“您已配置有效的 AWS 凭证。要我使用 SigV4（多个 Agent 空间和管理员工具）为您设置 DevOps Agent 吗？还是您更想改为设置承载令牌（单个 Agent 空间）？”
否	否	“您既未配置承载令牌，也未配置 AWS 凭证。您希望通过承载令牌（单个 Agent 空间）还是 AWS 凭证 / SigV4（多个 Agent 空间和管理员工具）进行连接？”然后指导用户完成所选方式的设置。

如果用户想设置承载令牌，请引导他们查看 AWS 文档：连接到 DevOps Agent 远程服务， 或根据本文档中的步骤指导他们创建访问令牌。

在用户确认选择之前，不要继续执行步骤 3。

---

步骤 3：验证连接

如果 aws-devops-agent MCP 服务已在运行，请检查能否列出工具。如果可以，则表示连接已验证。

否则，请继续操作。

在编写 .mcp.json 之前先进行验证。这可以确认凭证能否连接到实时端点。也可以用此方法验证现有的 MCP 服务配置。

承载令牌验证

curl -s -w "\nHTTP_STATUS: %{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEVOPS_AGENT_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp"

结果	含义	操作
HTTP 200 + result.tools 数组	成功	继续执行步骤 4
HTTP 401	令牌无效或已过期	告知用户在 Operator Web App 中创建新令牌
HTTP 403	令牌权限范围不足	告知用户令牌需要 agent:read + agent:operate 权限范围
连接被拒绝／超时	无法访问端点	如果 SigV4 可用，提供备用方案。否则报告服务不可用。

SigV4 验证

timeout 30 bash -c '
{
echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"setup-check\",\"version\":\"1.0\"}}}"
sleep 0.5
echo "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}"
sleep 0.5
echo "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"
sleep 8
} | uvx mcp-proxy-for-aws-cli@latest "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp" --service aidevops --region "$DEVOPS_AGENT_REGION"
'

**注意：**首次运行可能需要 10-15s，因为 uvx 会下载 mcp-proxy-for-aws-cli 及其依赖项。后续运行几乎是即时的。

结果	含义	操作
第二行包含 result.tools	成功	继续执行步骤 4
无输出／超时	凭证无效或无法访问端点	再次检查 aws sts get-caller-identity
stderr 中出现 ExpiredTokenException	AWS 会话已过期	告知用户重新进行身份验证（aws sso login 或刷新凭证）
AccessDeniedException	缺少 IAM 权限	用户需要为其角色配置 DevOps Agent 权限

---

步骤 4：确认并写入 .mcp.json

写入前，请向用户确认：

“我已确认连接正常。现在将把 [Bearer token / SigV4] MCP 服务添加到插件的 .mcp.json。是否继续？”

只有在用户确认后才写入。只写入一个服务条目，绝不能同时写入两个。将 MCP 配置安装到 ${CLAUDE_PLUGIN_ROOT}/.mcp.json。你也可以提出将 MCP 服务安装到工作区级别。安装选项如下：

• 插件级：${CLAUDE_PLUGIN_ROOT}/.mcp.json（默认）
• 项目级：.mcp.json（位于项目目录中，受版本控制）
• 特定项目级：.claude/settings.local.json（位于项目目录中）

Bearer 配置

{
  "mcpServers": {
    "aws-devops-agent": {
      "type": "http",
      "url": "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp",
      "headers": {
        "Authorization": "Bearer ${DEVOPS_AGENT_TOKEN}"
      },
      "timeout": 120000
    }
  }
}

SigV4 配置

将 <REGION> 替换为用户的实际区域：

{
  "mcpServers": {
    "aws-devops-agent": {
      "command": "uvx",
      "timeout": 120000,
      "args": [
        "mcp-proxy-for-aws-cli@latest",
        "https://connect.aidevops.<REGION>.api.aws/mcp",
        "--service", "aidevops",
        "--region", "<REGION>"
      ]
    }
  }
}

回退方案（aws-mcp）

仅当主要的 aws-devops-agent 端点无法访问，且有可用的 SigV4 凭证时，才添加：

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "timeout": 100000,
      "args": [
        "mcp-proxy-for-aws-cli@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata",
        "AWS_REGION=us-east-1"
      ]
    }
  }
}

仅针对 SigV4：写入新的 MCP 配置后，告知用户 MCP 服务已成功写入。然后进入下一步。

---

步骤 5：多空间路由（仅限 SigV4）

SigV4 设置成功后，发现并配置 AgentSpace 路由：

1. 通过新连接的 MCP 调用 list_agent_spaces，发现可用空间
2. 向用户展示列表
3. 如果有多个空间，将路由指南写入 .claude/aws-agents-for-devsecops.md：

# AWS DevOps Agent — Routing Guide

| Space | Agent Space ID | Purpose |
|-------|----------------|---------|
| <name> | <id> | <ask user> |

1. 指示用户：针对特定空间时，每次调用工具都传入 agent_space_id。

---

步骤 6：重新加载插件

告知用户需要运行 /reload-plugins 以启动新的 MCP 服务。你可能 需要提示用户运行该命令。还要提到，重启 MCP 服务后，他们可以尝试以下提示词：

• 设置多空间路由（仅限 SigV4）
• <从 ${CLAUDE_PLUGIN_ROOT}/README.md 列出技能和提示词建议>

---

Bearer token 指南（适用于需要创建 token 的用户）

1. 打开适用于其 AgentSpace 的 AWS DevOps Agent Operator Web App

2. 前往 Settings → Access tokens → Generate token

3. 创建一个权限为 Operate 的 token

4. 设置环境变量：

   export DEVOPS_AGENT_TOKEN="<your-token>"
   export DEVOPS_AGENT_REGION="<your-region>"
   

   可用区域：https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent-supported-regions.html

5. 重启 Claude Code（它会从启动它的 shell 中读取环境变量）

重要： 如果没有 Operate 权限，chat 和 investigate 工具将完全不可见——不是调用失败，而是不会出现在工具列表中。

---

SigV4 指南（适用于需要配置 AWS 凭证的用户）

1. 如果尚未安装 uvx，请安装：

   • macOS：brew install uv
   • Linux：curl -LsSf https://astral.sh/uv/install.sh | sh

2. 配置 AWS 凭证：

   aws configure sso --profile devops-agent
   aws sso login --profile devops-agent
   export AWS_PROFILE=devops-agent
   

3. 设置区域：

   export DEVOPS_AGENT_REGION="<your-region>"
   

4. 验证：aws sts get-caller-identity

5. IAM 角色必须具有 DevOps Agent 权限（例如，具有 aidevops 访问权限的托管策略）

重要： 使用 SigV4 时，请取消设置 DEVOPS_AGENT_TOKEN。如果两者都已设置，客户端可能会尝试使用 Bearer 身份验证，而不是签名代理。

---

故障排除

错误	原因	修复方法
看不到任何工具	未设置 token 或未重启 Claude Code	设置 DEVOPS_AGENT_TOKEN + DEVOPS_AGENT_REGION，然后重启
HTTP 401	token 无效或已过期	在 Operator Web App 中创建新 token
缺少 chat/investigate	token 范围仅为 agent:read	创建范围为 agent:operate 的 token
连接被拒绝 / 超时	端点无法访问	检查网络；如果有可用的 SigV4，提供 aws-mcp 回退方案
ExpiredTokenException	AWS 会话凭证已过期	运行 aws sso login 或刷新凭证
AccessDeniedException（SigV4）	缺少 IAM 权限	使用具有 DevOps Agent 访问权限的角色
代理无法启动	未安装 uvx	运行 brew install uv（macOS）或按平台说明安装
工具可见但调用超时	chat 的正常情况（5-30s）	确保 mcp.json 中有 "timeout": 120000