diff --git a/README.md b/README.md index 50be386..548da35 100644 --- a/README.md +++ b/README.md @@ -62,3 +62,18 @@ chmod +x deploy.sh && ./deploy.sh | `deploy.sh` | One-command ECR + IAM + AgentCore deployment | | `iam/execution-role.json` | Least-privilege IAM trust + permissions policy | | `developer-configs/` | IDE configs for Claude Desktop, Cursor, VS Code | + + +## Diagrams + +### System overview +![Architecture](docs/architecture.svg) + +### Container startup +![Startup](docs/startup.svg) + +### Request lifecycle +![Request](docs/request.svg) + +### Deployment steps +![Deploy](docs/deploy.svg) \ No newline at end of file diff --git a/docs/cq_mcp_1_overview.svg b/docs/cq_mcp_1_overview.svg new file mode 100644 index 0000000..f4bc667 --- /dev/null +++ b/docs/cq_mcp_1_overview.svg @@ -0,0 +1,89 @@ + + CloudQuery MCP — System overview + Three zones: developer machines, AgentCore runtime, and AWS data layer + + + + + + + + + Developer machines + + + Claude Desktop + mcp-remote + SigV4 + + + + Cursor IDE + mcp-remote + SigV4 + + + + VS Code + mcp-remote + SigV4 + + + + AWS credentials + InvokeAgentRuntime + + + + + + + HTTPS + + + + Bedrock AgentCore · us-east-1 + + + IAM authorizer + validates SigV4 + + + + Session router + Mcp-Session-Id → MicroVM + + + + MicroVM + cq-platform-mcp :8080 + + + + ECR + cloudquery-mcp image + + + + + + TLS + + + + AWS data layer + + + RDS PostgreSQL + cq_inventory + + + + Secrets Manager + pg-conn secret + + + + CloudQuery CLI + syncs AWS assets + + + + \ No newline at end of file diff --git a/docs/cq_mcp_2_startup.svg b/docs/cq_mcp_2_startup.svg new file mode 100644 index 0000000..4fcdea6 --- /dev/null +++ b/docs/cq_mcp_2_startup.svg @@ -0,0 +1,67 @@ + + CloudQuery MCP — Container startup sequence + Five steps from ECR pull to cq-platform-mcp serving requests + + + + + + + + + + ECR pull + cq-platform-mcp + + + + + + + entrypoint.sh + Python starts + + + + + + + Secrets Manager + GetSecretValue via IAM + + + + + + + os.execv() + replaces Python + + + + + + + MCP server + :8080/mcp ready + + + + IAM role on MicroVM + reads POSTGRES_SECRET_ARN + conn string in memory only + PID 1 = Go binary + no Python remains + + + + + + + + + + + No credentials in the image, env vars, or disk + The IAM role is the only auth surface — revoke it to cut all access instantly + \ No newline at end of file diff --git a/docs/cq_mcp_3_request.svg b/docs/cq_mcp_3_request.svg new file mode 100644 index 0000000..b6991f3 --- /dev/null +++ b/docs/cq_mcp_3_request.svg @@ -0,0 +1,103 @@ + + CloudQuery MCP — Request lifecycle + Full round-trip from developer tool call through AgentCore to RDS and back + + + + + + + + + + IDE + + + + mcp-remote + + + + AgentCore + + + + MicroVM + + + + RDS + + + + + + + + + + + + call tool + + + + + sign SigV4 + + HTTPS + + + + IAM check + + + + + POST /mcp + + + + + SQL + + + + + + + rows + + + + + + format MCP + + + + HTTP 200 + + + + unwrap + + + + tool result + + + + Session stickiness + Mcp-Session-Id routes to same MicroVM + + + + request + + response + + SQL over TLS + + IDE ↔ mcp-remote + \ No newline at end of file diff --git a/docs/cq_mcp_4_deploy.svg b/docs/cq_mcp_4_deploy.svg new file mode 100644 index 0000000..155315c --- /dev/null +++ b/docs/cq_mcp_4_deploy.svg @@ -0,0 +1,81 @@ + + CloudQuery MCP — deploy.sh steps + Five sequential steps run by deploy.sh to provision the full stack + + + + + + + + + + 1 · ECR repo + create if missing + scan on push + + + + + + + 2 · Docker build + linux/amd64 + push to ECR + + + + + + + 3 · IAM role + trust policy + permissions policy + idempotent + + + + + + + 4 · AgentCore + register endpoint + MCP · port 8080 + env vars injected + + + + + + + 5 · Configs + claude_desktop + cursor · vscode + real URL baked in + + + + + Before running deploy.sh + export POSTGRES_SECRET_ARN=arn:aws:secretsmanager:us-east-1:ACCOUNT:secret:cloudquery/pg-conn-XxXx + aws, docker, python3 on PATH · IAM user needs ecr · iam · bedrock-agentcore permissions + + + + After deploy.sh completes + + + + MCP endpoint URL printed + + + + developer-configs/ written + + + + IAM role live in account + + developers need: npm install -g mcp-remote · then copy their config file + + \ No newline at end of file