Amazon Q Developer lokal: Dokumentation abfragen & Diagramme generieren

6. Mai 2025 - Daniel

Einleitung – Fokus auf Technik, nicht Marketing

Amazon Q Developer ist ein schlankes CLI‑ und LSP‑Frontend für die generativen Foundation‑Modelle von AWS.
Die Anwendung läuft vollständig lokal, authentifiziert sich wahlweise mit einer Builder ID oder klassischen AWS‑Credentials und nutzt dabei konfigurierbare gRPC‑basierte MCP‑Server (Multi‑Party Computation).

  • Architektur → Q übersetzt Prompts in strukturierte RPC‑Aufrufe.
  • Documentation‑Server liefert JSON‑Antworten aus den AWS‑Docs.
  • Diagram‑Server rendert Graphviz‑DOT zu SVG/PNG.

Ziel dieses Beitrags ist eine reproduzierbare Einrichtung inklusive:

  1. Installation der Q‑CLI unter Fedora/WSL2.
  2. Anbindung zweier MCP‑Module (Doku & Diagramm).
  3. Beispiel‑Prompts, die Output‑Pipelining demonstrieren.

1 - System‑Voraussetzungen

Paket Version Zweck
Fedora / WSL2 42 Testumgebung in diesem Guide
Python ≥ 3.10 Runtime für uvx & MCP‑Server
uv + uvx 0.2.x Paket‑ & App‑Runner
Graphviz 2.50+ Backend für Diagramm‑Renderings
Amazon Builder ID n/a AuthN‑Flow für Q‑CLI

2 – Installation der Amazon Q Developer CLI

2.1 - CLI herunterladen

https://docs.aws.amazon.com/de_de/amazonq/latest/qdeveloper-ug/command-line-installing.html

Für Linux:

curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" -o "q.zip"
unzip q.zip
./q/install.sh

Andere fertige .deb, AppImage & ZIP‑Pakete findest du unter: https://docs.aws.amazon.com/de_de/amazonq/latest/qdeveloper-ug/command-line-installing.html

2.2 - Smoke-Tests

q --version
q doctor

2.3 - Anmelden

q login

Builder ID auswählen → Login bestätigen.

Alternativ IAM Identity Center oder AWS‑Keys.

Nach erfolgreichem Login beantwortet Q deine ersten Fragen direkt im Terminal.

3 - Python‑Umgebung & MCP‑Server

3.1 - Python 3.10 & venv

sudo dnf update && sudo dnf install -y python3.10 
python3.10 -m venv ~/aws-q-env
source ~/aws-q-env/bin/activate

3.2 - Graphviz installieren

Der Diagram‑MCP‑Server nutzt intern Graphviz, um SVG/PNG zu rendern.

sudo dnf install -y graphviz           
dot -V

Wenn Graphviz fehlt, erzeugt der Server nur JSON‑Layouts – keine fertigen Bilder.

3.3 - Python 3.10 & venv

pip install --upgrade pip
pip install uv   # installiert uv & uvx
pip install awslabs.aws-diagram-mcp-server \
            awslabs.aws-documentation-mcp-server \
            trio

3.4 – Amazon Q mit lokalen Servern verknüpfen

{
  "mcpServers": {
    "awslabs.aws-diagram-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-diagram-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "autoApprove": [],
      "disabled": false
    },
    "awslabs.aws-documentation-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}

Beim nächsten CLI‑Start spawnt Q beide Server automatisch im Hintergrund

Schritt 5 – Amazon Q starten

q

 Wie funktioniert das eigentlich?

Du schreibst einen Prompt in der CLI oder VS Code. Amazon Q analysiert den Text und wählt – basierend auf Tool‑Hints – einen passenden MCP‑Server (z. B. „Dokumentation suchen“). Q ruft die Server‑API lokal auf (kein Datentransfer zu AWS nötig). Das Ergebnis (z. B. JSON‑Snippet oder SVG) wird zurück‑gerendert. Chain‑of‑Thought möglich: Du kannst die Ausgabe direkt weiterverwenden (→ Diagramm generieren, Code ergänzen usw.).

 Beispiel-Prompts

Doku‑Recherche & Quellenangabe

Look up documentation on S3 bucket naming rule. Cite your sources.

Based on the AWS documentation, here are the S3 bucket naming rules:

## S3 Bucket Naming Rules

### Length and Character Requirements
• Bucket names must be between 3 and 63 characters long
• Can only contain lowercase letters, numbers, periods (.), and hyphens (-)
• Must begin and end with a letter or number
• Must not contain two adjacent periods
• Must not be formatted as an IP address (e.g., 192.168.5.4)

### Prefix and Suffix Restrictions
• Must not start with the prefix xn--
• Must not start with the prefix sthree-
• Must not start with the prefix amzn-s3-demo-
• Must not end with the suffix -s3alias (reserved for access point alias names)
• Must not end with the suffix --ol-s3 (reserved for Object Lambda Access Point alias names)
• Must not end with the suffix .mrap (reserved for Multi-Region Access Point names)
• Must not end with the suffix --x-s3 (reserved for directory buckets)
• Must not end with the suffix --table-s3 (reserved for S3 Tables buckets)

### Additional Rules
• Buckets used with Amazon S3 Transfer Acceleration can't have periods (.) in their names
• Bucket names must be unique across all AWS accounts in all AWS Regions within a partition
• After a bucket is deleted, the name becomes available for reuse, but there's no guarantee you can reuse it immediately

### Best Practices
• Choose a bucket naming scheme that's unlikely to cause naming conflicts
• Append globally unique identifiers (GUIDs) to bucket names
• Avoid using periods (.) in bucket names except for static website hosting
• Choose relevant names that don't include terms like "AWS" or "Amazon"
• Don't delete buckets just to reuse bucket names

Source: [AWS Documentation - General purpose bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html)

Look up AWS documentation for creating an AWS Organizations OU structure for a large enterprise with multiple teams. Cite your sources.

Q nutzt den Documentation‑MCP‑Server und liefert u. a.:

Erstelle Diagram mit AWS Organisationen

Create a diagram showing an AWS Organizations hierarchy with a Root, three OUs (Shared Services, Sandbox, Production) and individual accounts for Team A and Team B under Sandbox and Production.

Q nutzt den Diagram‑MCP‑Server und liefert ein Diagram erstellt mit hilfe von Graphviz

I've created a diagram showing the AWS Organizations hierarchy you requested. The diagram is saved at /home/daniel/generated-diagrams/diagram_9c62d09a.png.

The diagram illustrates:

1. Organization Root - The top-level container for all accounts and OUs

2. Three main Organizational Units (OUs):

   • **Shared Services OU** - Contains centralized accounts that provide services to the entire organization:
     • Network Account
     • Security Account
     • Logging Account

   • **Sandbox OU** - Development and testing environment:
     • Team A Sandbox Account
     • Team B Sandbox Account

   • **Production OU** - Production environment:
     • Team A Production Account
     • Team B Production Account

The structure follows a common pattern where teams have dedicated accounts in both sandbox and production environments, while shared services are centralized in their own OU. This approach provides:

• Clear separation between development and production environments
• Team isolation for better security and cost tracking
• Centralized management of common services
• Simplified policy application at the OU level

This organization structure is ideal for companies with multiple teams that need their own environments while sharing common infrastructure services.

Diagram

Was noch? :)

aws bietet noch weitere MCP server auf ihrer github seite https://github.com/awslabs/mcp Auch ganz spannend wäre es den "Cost Analysis MCP Server" anzunhänken.