diff --git a/docs/architecture.svg b/docs/architecture.svg new file mode 100644 index 0000000..1847f4a --- /dev/null +++ b/docs/architecture.svg @@ -0,0 +1,75 @@ + + 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 + + + diff --git a/docs/cq_mcp_1_overview.svg b/docs/cq_mcp_1_overview.svg deleted file mode 100644 index f4bc667..0000000 --- a/docs/cq_mcp_1_overview.svg +++ /dev/null @@ -1,89 +0,0 @@ - - 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 deleted file mode 100644 index 4fcdea6..0000000 --- a/docs/cq_mcp_2_startup.svg +++ /dev/null @@ -1,67 +0,0 @@ - - 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 deleted file mode 100644 index b6991f3..0000000 --- a/docs/cq_mcp_3_request.svg +++ /dev/null @@ -1,103 +0,0 @@ - - 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 deleted file mode 100644 index 155315c..0000000 --- a/docs/cq_mcp_4_deploy.svg +++ /dev/null @@ -1,81 +0,0 @@ - - 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 diff --git a/docs/deploy.svg b/docs/deploy.svg new file mode 100644 index 0000000..4e277e7 --- /dev/null +++ b/docs/deploy.svg @@ -0,0 +1,79 @@ + + 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 + + + + + 4a · Runtime + create-agent-runtime + container config + env vars injected + + + + + 4b · Endpoint + create-agent-runtime + -endpoint + returns public URL + + + + Before running + export POSTGRES_SECRET_ARN=arn:aws:secretsmanager:... + aws · docker · python3 on PATH + + + + After completion + MCP endpoint URL printed to terminal + developer-configs/ written with real URL + + + + npm install -g mcp-remote + + + copy config from developer-configs/ + + + connect IDE → done + + Developer one-time setup (after deploy.sh completes) + diff --git a/docs/request.svg b/docs/request.svg new file mode 100644 index 0000000..a987540 --- /dev/null +++ b/docs/request.svg @@ -0,0 +1,105 @@ + + CloudQuery MCP — Request lifecycle + Full round-trip from developer tool call through AgentCore to RDS and back + + + + + + + + + + + + + + + + + + + IDE + + + mcp-remote + + + AgentCore + + + MicroVM + + + RDS PostgreSQL + + + + + + + + + + + call tool + + + + sign SigV4 + + HTTPS + + + IAM check + + + + POST /mcp + + + + execute SQL + + + + + result 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 + diff --git a/docs/startup.svg b/docs/startup.svg new file mode 100644 index 0000000..ec5c420 --- /dev/null +++ b/docs/startup.svg @@ -0,0 +1,65 @@ + + 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 role + + + + + os.execv() + replaces Python + + + + + MCP server + :8080/mcp ready + + + + + + + + + IAM role on MicroVM + reads SECRET_ARN env + conn string in memory + 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 +