调试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-nameAWS+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服务器。
先决条件：
如何使用
调试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服务器使用 工具发现网关 图案：
- 单工具界面：暴露一个
debug()克劳德的工具，而不是17个单独的工具 - 代币减少约95%：将上下文从~13K令牌减少到~500令牌（仅限工具列表）
- 基于类别的发现：按类别组织的工具（cloudwatch、stepfunctions、langsmith、jira）
- 直接实施：直接使用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 Managerdev-用途DEV/env/vars来自AWS Secrets Managerlocal-负载来自.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 Managerprod/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 CodeJira配置
Jira集成允许您直接从Claude Code搜索门票并获取完整的门票详细信息。
步骤1：创建Jira API令牌
- 首选 Atlassian API代币管理
- 点击 创建API令牌
- 给它一个描述性标签（例如“调试MCP”）
- 复制生成的令牌（您将不会再看到它）
第二步：收集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参数）。
配置参考
| 来源 | 名称 | 必填 | 描述 |
|---|---|---|---|
| CLI参数 | --jira-host | 是 | Jira Cloud主机名（例如。， company.atlassian.net) |
| CLI参数 | --jira-email | 是 | Atlassian帐户电子邮件 |
| CLI参数 | --jira-project | 是 | 默认Jira项目密钥（例如。， PROJ) |
| CLI参数 | --jira-token | 是\* | Jira API令牌 |
Env 是。 JIRA_API_TOKEN | 是\* | 替代 --jira-token CLI参数 |
\*要么 --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-profileCLI参数 - 确保配置文件存在于
~/.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() 带有模式和处理程序的装饰器。
团队共享
与您的团队分享：
- 他们更新
--aws-profile使用自己的个人资料名称 - 可选择调整
--aws-region如果不同 - 所有17个调试工具都可以通过单一
debug()网关-无需工具过滤
贡献
欢迎投稿！一些需要公关的领域：
- LangSmith CLI令牌支持：目前，LangSmith凭据是从AWS Secrets Manager加载的（用于
prod/dev)或.env文件（用于local).添加--langsmith-api-keyCLI参数支持（类似于Jira）将使不使用Secrets Manager的团队更容易进行设置。 - 附加调试工具：其他AWS服务的新工具（ECS、Lambda日志、X射线跟踪）
- 错误修复与改进：错误处理、文档、测试
贡献：
- 复刻仓库
- 创建要素分支
- 进行更改（请参见 添加新工具 在CLAUDE.md中）
- 提交PR
许可证
MIT许可证-请参阅许可证文件