AWS debug MCP

调试MCP

MCP服务器，用于直接从Claude Code或任何MCP客户端调试分布式系统（AWS CloudWatch日志、步骤函数、LangSmith、Jira）。

状态: ✅ 完成-单一网关工具，展示17个调试工具 上下文缩减：约95%的代币节省（13K→ ~500 代币） 仓库: https://github.com/Coykto/debug_mcp

快速开始

安装

选项1：使用Claude Code CLI（推荐）

仅限AWS：

claude mcp add --scope user --transport stdio debug-mcp \
    -- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
    --aws-region us-west-2 \
    --aws-profile your-aws-profile-name

AWS+Jira：

claude mcp add --scope user --transport stdio debug-mcp \
    -- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
    --aws-region us-west-2 \
    --aws-profile your-aws-profile-name \
    --jira-host yourcompany.atlassian.net \
    --jira-email your.email@company.com \
    --jira-project PROJ \
    --jira-token your-api-token

选项2：手动配置 .mcp.json

仅限AWS：

{
  "mcpServers": {
    "debug-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Coykto/debug_mcp",
        "debug-mcp",
        "--aws-region", "us-west-2",
        "--aws-profile", "your-aws-profile-name"
      ]
    }
  }
}

AWS+Jira：

{
  "mcpServers": {
    "debug-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Coykto/debug_mcp",
        "debug-mcp",
        "--aws-region", "us-west-2",
        "--aws-profile", "your-aws-profile-name",
        "--jira-host", "yourcompany.atlassian.net",
        "--jira-email", "your.email@company.com",
        "--jira-project", "PROJ",
        "--jira-token", "your-api-token"
      ]
    }
  }
}

备注：配置作为CLI参数传递，以解决 Claude代码中的已知错误 其中环境变量不能可靠地传递给MCP服务器。

先决条件：

• Python 3.11+
• uvx 已安装(安装指南)
• 已配置AWS凭据(aws configure)
• 对于Jira:来自的API令牌 亚托西亚 （参见 Jira配置)

如何使用

调试MCP暴露了 单网关工具 称为 debug() 它提供了17个调试工具的发现和执行：

发现模式

请Claude查找可用工具：

"What debugging tools are available?"
→ Claude calls: debug(tool="list")

"What CloudWatch tools are available?"
→ Claude calls: debug(tool="list:cloudwatch")

"List all Step Functions tools"
→ Claude calls: debug(tool="list:stepfunctions")

执行模式

问克劳德自然语言问题，它将使用适当的工具：

CloudWatch日志：

• “列出所有Lambda日志组”
• “在/aws/lambda/my函数中搜索上个小时的错误”
• “分析/aws/lambda/my函数日志中的模式”
• “在我的Lambda日志上运行CloudWatch Insights查询”

步骤功能调试：

• “列出我的所有Step Function状态机”
• “显示状态机X的工作流定义和Lambda函数”
• “显示过去3天状态机X的失败执行”
• “获取包括工作流定义在内的执行详细信息”
• “查找匹配状态输出包含‘company’的执行，并向我显示Lambda ARN”

LangSmith追踪：

• “在prod环境中列出我的LangSmith项目”
• “显示生产中最后一小时的错误运行”
• “获取LangSmith在开发中运行abc-123的详细信息”
• “搜索包含特定错误消息的对话”

Jira门票：

• “在待办事项状态下搜索错误”
• “查找分配给我的票”
• “获取PROJ-123票的详细信息”
• “显示所有正在进行的身份验证故事”

Claude会自动将您的问题翻译成适当的 debug() 使用正确的工具名称和参数进行调用。

运作原理

此MCP服务器使用 工具发现网关 图案：

1. 单工具界面：暴露一个 debug() 克劳德的工具，而不是17个单独的工具
2. 代币减少约95%：将上下文从~13K令牌减少到~500令牌（仅限工具列表）
3. 基于类别的发现：按类别组织的工具（cloudwatch、stepfunctions、langsmith、jira）
4. 直接实施：直接使用boto3和SDK（无AWS MCP代理）

网关架构

debug(tool="list")                     → List categories
debug(tool="list:cloudwatch")          → List CloudWatch tools
debug(tool="describe_log_groups", ...) → Execute tool

所有17个调试工具仍然可用——它们只是通过网关访问，而不是单独暴露。

可用工具（通过Gateway）

CloudWatch日志（4个工具）

• describe_log_groups -列出CloudWatch日志组
• analyze_log_group -分析日志中的异常和模式
• execute_log_insights_query -运行CloudWatch Insights查询
• get_logs_insight_query_results -获取查询结果

步骤功能（5个工具）

调试：

• list_state_machines -列出所有状态机（获取ARN）
• get_state_machine_definition -使用提取的Lambda ARN和资源获取ASL定义
• list_step_function_executions -使用筛选列出执行情况
• get_step_function_execution_details -通过状态输入/输出获取完整的执行细节
• search_step_function_executions -具有状态/输入/输出模式匹配的高级搜索

定义和资源： 这 get_state_machine_definition 工具提取：

• 完整的亚马逊州语言（ASL）工作流定义
• 工作流中使用的Lambda函数ARN
• 其他资源（SNS主题、SQS队列、DynamoDB表、嵌套状态机）
• IAM角色、日志记录和跟踪配置

您还可以使用以下命令将定义与执行细节一起包含在内 include_definition=True 在：

• get_step_function_execution_details -请参阅执行数据旁边的工作流定义
• search_step_function_executions -查看具有筛选执行结果的定义

LangSmith（6工具）

跟踪和调试：

• list_langsmith_projects -列出可用的LangSmith项目
• list_langsmith_runs -列出带有过滤功能的运行/跟踪（类型、错误、时间范围）
• get_langsmith_run_details -通过输入/输出和子运行（存储在内存中）获取完整的运行详细信息
• search_langsmith_runs -搜索包含特定文本的对话
• search_run_content -在存储的跑步内容中进行语义搜索
• get_run_field -从存储的运行中获取特定字段

多环境支持： 每个LangSmith工具都需要一个 environment 参数：

• prod -用途 PRODUCTION/env/vars 来自AWS Secrets Manager
• dev -用途 DEV/env/vars 来自AWS Secrets Manager
• local -负载来自 .env 使用python dotenv的文件

Secrets Manager中的凭据： 您的AWS Secrets Manager机密应包含：

• LANGCHAIN_API_KEY -您的LangSmith API密钥
• LANGCHAIN_PROJECT -默认项目名称（可选）

本地开发（.env文件）：

LANGCHAIN_API_KEY=ls_your_api_key_here
LANGCHAIN_PROJECT=your-project-name

备注：LangSmith集成目前需要AWS Secrets Manager prod/dev 环境（这是我们团队存储凭据的方式）。如果您想将LangSmith与直接CLI令牌参数一起使用（类似于Jira），欢迎PR！

Jira（2个工具）

• search_jira_tickets -使用过滤器（类型、状态、受让人）和文本搜索搜索门票
• get_jira_ticket -获取完整的工单详细信息，包括链接的问题、附件、子任务和Epic子任务

返回的字段为 get_jira_ticket:

• 基本：密钥、摘要、描述、状态、问题类型、优先级、受让人、报告人、标签、创建、更新
• 关系：linked_issues、parent（用于子任务）、subtask、epic_children（用于Epics）
• 附件：文件名列表

配置

AWS身份验证

将AWS凭据作为CLI参数传递（建议解决此问题 克劳德代码环境变量错误):

# Using Claude Code CLI
claude mcp add --scope user --transport stdio debug-mcp \
    -- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
    --aws-region us-west-2 \
    --aws-profile your-profile-name

或在 .mcp.json:

"args": [
  "--from", "git+https://github.com/Coykto/debug_mcp",
  "debug-mcp",
  "--aws-region", "us-west-2",
  "--aws-profile", "your-profile-name"
]

替代：在启动Claude Code之前设置环境变量：

export AWS_REGION=us-west-2
export AWS_PROFILE=your-profile-name
# Then launch Claude Code

Jira配置

Jira集成允许您直接从Claude Code搜索门票并获取完整的门票详细信息。

步骤1：创建Jira API令牌

1. 首选 Atlassian API代币管理
2. 点击 创建API令牌
3. 给它一个描述性标签（例如“调试MCP”）
4. 复制生成的令牌（您将不会再看到它）

第二步：收集Jira详细信息

您需要：

• 主机：您的Jira Cloud主机名（例如。， yourcompany.atlassian.net)
• 电子邮件：与您的Atlassian帐户关联的电子邮件地址
• 项目：默认项目的项目密钥（例如。， PROJ, DEV, CORE)
• 代币：步骤1中的API令牌

步骤3：配置调试MCP

选项A:Claude代码命令行界面（推荐）

claude mcp add --scope user --transport stdio debug-mcp \
    -- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
    --aws-region us-west-2 \
    --aws-profile your-profile-name \
    --jira-host yourcompany.atlassian.net \
    --jira-email your.email@company.com \
    --jira-project PROJ \
    --jira-token your-api-token

选项B：手动 .mcp.json 配置

{
  "mcpServers": {
    "debug-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/Coykto/debug_mcp",
        "debug-mcp",
        "--aws-region", "us-west-2",
        "--aws-profile", "your-profile-name",
        "--jira-host", "yourcompany.atlassian.net",
        "--jira-email", "your.email@company.com",
        "--jira-project", "PROJ",
        "--jira-token", "your-api-token"
      ]
    }
  }
}

选项C：为令牌使用环境变量

如果您不希望在配置中存储令牌，请设置 JIRA_API_TOKEN 作为启动Claude Code之前的环境变量：

export JIRA_API_TOKEN=your-api-token

然后省略 --jira-token 从CLI参数中提取（仍需要其他Jira参数）。

配置参考

\*要么 --jira-token 或 JIRA_API_TOKEN 是必需的。

Jira故障排除

“Jira凭据未配置”错误：

• 验证是否提供了所有必需的参数： --jira-host, --jira-email, --jira-project，和令牌
• 检查您的API令牌在 大西洋API代币

“401未经授权”错误：

• 您的API令牌可能已过期-创建一个新令牌
• 验证电子邮件是否与您的Atlassian帐户完全匹配

“找不到项目”错误：

• 检查项目密钥（不是名称）-它是票证ID中的前缀（例如。， PROJ 在 PROJ-123)
• 确保您的帐户可以访问该项目

故障排除

服务器无法启动

• 检查AWS凭据： aws sts get-caller-identity --profile YOUR_PROFILE
• 验证是否安装了uvx： uvx --version
• 检查Claude Code MCP登录设置

AWS区域/帐户错误

• 更新 --aws-region 和 --aws-profile CLI参数
• 确保配置文件存在于 ~/.aws/credentials
• 验证区域是否正确： aws configure get region --profile YOUR_PROFILE

环境变量不起作用

由于a Claude代码中的已知错误，MCP中的环境变量 env 块不能可靠地传递给服务器。 改用CLI参数 （见上面的安装示例）。

发展

地方发展

# Install dependencies
uv sync

# Run the server locally
uv run debug-mcp --aws-region us-west-2 --aws-profile your-profile

# Test
uv run pytest

建筑

服务器使用 工具发现网关 直接boto3/SDK实现的模式：

网关层 (src/debug_mcp/server.py):

• 单 debug() 工具暴露给克劳德
• 处理发现(tool="list", tool="list:cloudwatch")
• 将执行路由到已注册的工具
• 使用Pydantic模型验证参数

注册系统 (src/debug_mcp/registry.py):

• 所有具有模式的工具的中央注册表
• 基于类别的组织
• @debug_tool() 注册装饰师
• 验证和执行路由

工具实施:

• 云监控 (cloudwatch_logs.py + cloudwatch_registry.py)：boto3 CloudWatch日志客户端
• 阶跃函数 (stepfunctions.py + stepfunctions_registry.py)：boto3步骤功能客户端
• 朗史密斯 (langsmith.py + langsmith_registry.py)：支持多环境的LangSmith SDK
• Jira (jira.py + jira_registry.py)：具有延迟客户端初始化的Jira SDK

每 *_registry.py 使用文件注册工具 @debug_tool() 带有模式和处理程序的装饰器。

团队共享

与您的团队分享：

1. 他们更新 --aws-profile 使用自己的个人资料名称
2. 可选择调整 --aws-region 如果不同
3. 所有17个调试工具都可以通过单一 debug() 网关-无需工具过滤

贡献

欢迎投稿！一些需要公关的领域：

• LangSmith CLI令牌支持：目前，LangSmith凭据是从AWS Secrets Manager加载的（用于 prod/dev)或 .env 文件（用于 local).添加 --langsmith-api-key CLI参数支持（类似于Jira）将使不使用Secrets Manager的团队更容易进行设置。
• 附加调试工具：其他AWS服务的新工具（ECS、Lambda日志、X射线跟踪）
• 错误修复与改进：错误处理、文档、测试

贡献：

1. 复刻仓库
2. 创建要素分支
3. 进行更改（请参见 添加新工具 在CLAUDE.md中）
4. 提交PR

许可证

MIT许可证-请参阅许可证文件