Ghost Dev MCP

AWS Ghost开发人员--MCP无服务器代理

版本：1.0

在AWS Lambda上运行的MCP（模型上下文协议）服务器，充当AI助手（Claude、Cursor）和AWS基础设施之间的安全代理。它为AI提供了对系统的只读访问权限，因此它可以帮助调查事件，而不需要人工复制粘贴日志。

______________________________________________________________________

它做什么（v1.0）

此版本侧重于 分诊 --从两个来源收集原始数据的速度足够快，以至于人工智能可以总结出失败的原因和位置。

诚实的范围

v1.0帮助AI识别 症状 （错误消息、失败的有效载荷），但不会自动确定根本原因。它对以下方面最有用：

• 在非正常时间进行随叫随到的分流——将数据处理时间从30多分钟缩短到不到一分钟
• 让初级工程师在升级之前将上下文交给人工智能
• 手动复制粘贴日志是主要瓶颈的情况

确实如此 不 （尚未）涵盖：X射线服务图、部署相关性、基础设施指标。

______________________________________________________________________

建筑

Claude / Cursor
      │  HTTPS + x-api-key header
      ▼
API Gateway (HTTP API)
      │
      ▼  Lambda Authorizer (validates API key via Secrets Manager)
      ▼
Lambda: mcp-router
      ├── SQS   → list_dlqs, inspect_dlq_payload
      └── Logs  → search_log_groups, get_error_traces

两个云组堆栈：

• aws-ghost-developer-secrets-{env} -在机密管理器中管理API密钥
• aws-ghost-developer-{env} -Lambda、API网关、IAM角色（通过SAM部署）

______________________________________________________________________

先决条件

• AWS CLI已配置(aws configure)
• AWS-SAM-CLI(pip install aws-sam-cli)
• Python 3.12+
• openssl （默认情况下在macOS/Linux上可用；在Windows上使用Git Bash或WSL）

______________________________________________________________________

设置

1.克隆并安装依赖项

git clone 
cd aws-ghost-developer
pip install -r requirements.txt

2.在samconfig.toml中配置区域

打开 samconfig.toml 并更新区域以匹配您要部署的位置：

[default.deploy.parameters]
region = "ap-southeast-1"   # change this to your target region

注： bootstrap.sh 读取 AWS_DEFAULT_REGION 在运行时，但是 sam deploy 也拿起 region 从 samconfig.toml。保持它们同步，以避免部署到错误的区域。

3.运行bootstrap（一个命令即可完成所有操作）

export AWS_DEFAULT_REGION=ap-southeast-1   # must match samconfig.toml
./scripts/bootstrap.sh prod

这将：

1. 生成加密安全的API密钥
2. 部署 infra/secrets.yaml 将密钥存储在密钥管理器中
3. 构建和部署SAM堆栈
4. 打印MCP端点URL和配置代码段

对于其他环境：

./scripts/bootstrap.sh dev
./scripts/bootstrap.sh staging

最后，您将看到如下输出：

  {
    "mcpServers": {
      "aws-ghost-developer": {
        "url": "https://.execute-api.ap-southeast-1.amazonaws.com/mcp",
        "transport": "http",
        "headers": {
          "x-api-key": ""
        }
      }
    }
  }

复制 url 和 x-api-key 值——下一步您将需要它们。

4.添加到您的MCP客户端

Claude Code命令行界面（推荐）

claude mcp add --transport http aws-ghost-developer \
  https://.execute-api..amazonaws.com/mcp \
  --header "x-api-key:"

验证是否已添加：

claude mcp get aws-ghost-developer

克劳德桌面（macOS）

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aws-ghost-developer": {
      "url": "https://.execute-api..amazonaws.com/mcp",
      "transport": "http",
      "headers": {
        "x-api-key": ""
      }
    }
  }
}

光标

编辑 .cursor/mcp.json 在项目根目录（或全局Cursor MCP配置）中：

{
  "mcpServers": {
    "aws-ghost-developer": {
      "url": "https://.execute-api..amazonaws.com/mcp",
      "transport": "http",
      "headers": {
        "x-api-key": ""
      }
    }
  }
}

______________________________________________________________________

用法示例

一旦连接，你可以自然地问AI：

“检查支付服务的SQS队列中是否有任何失败的消息”

“看看订单处理者的死信队列，告诉我出了什么问题”

“查找身份验证服务的CloudWatch日志，并显示过去一小时的错误”

“在日志组中搜索'签出'，并查询过去30分钟内是否有5xx个错误”

______________________________________________________________________

项目结构

aws-ghost-developer/
├── src/
│   ├── handler.py              # Lambda entrypoint, MCP JSON-RPC router
│   ├── authorizer.py           # Lambda authorizer — validates x-api-key
│   ├── transport/
│   │   └── sse.py              # MCP response/error formatters
│   ├── tools/
│   │   ├── __init__.py         # Tool registry
│   │   ├── list_dlqs.py        # List SQS Dead Letter Queues
│   │   ├── inspect_dlq.py      # Peek at DLQ messages
│   │   ├── search_log_groups.py # Discover CloudWatch log groups
│   │   └── get_error_traces.py  # Query Logs Insights (async-safe)
│   └── utils/
│       ├── redact.py           # Auto-redact secrets from responses
│       └── secrets.py          # Secrets Manager wrapper with TTL cache
├── infra/
│   └── secrets.yaml            # CloudFormation — Secrets Manager stack
├── scripts/
│   ├── bootstrap.sh            # Full setup: secrets + SAM deploy
│   └── gen-secret.sh           # Secrets only (for key rotation)
├── tests/
│   └── unit/
├── template.yaml               # SAM template — Lambda + API Gateway
├── samconfig.toml              # SAM deploy defaults
└── requirements.txt

______________________________________________________________________

安全

• 所有工具都是 只读。未授予写入/删除权限。
• API密钥存储在AWS机密管理器中，从不存储在环境变量中。
• Lambda授权器使用恒定时间比较来验证每个请求。
• IAM角色遵循最小权限——每个权限都限定在所需的最小操作范围内。
• DLQ消息会被窥探30秒的可见性超时 从未删除.
• 消息有效载荷中的敏感值（密码、令牌）在返回给AI之前会自动编辑。

______________________________________________________________________

旋转API键

./scripts/gen-secret.sh prod

然后更新 mcp_config.json 使用新密钥。无需重新部署。

______________________________________________________________________

运行测试

pip install pytest
python -m pytest tests/unit/ -v

______________________________________________________________________

路线图

v1.0涵盖了分诊。计划用于未来版本：

• v1.1 --X射线服务图(get_service_map)追踪链中哪个服务出现故障
• v1.2 --部署相关性(get_recent_deployments)通过CloudTrail将错误链接到版本
• v2.0 --多区域支持，结构化RCA报告生成