Skip to content

How the examples were produced

From docs/MCP_TOOLS.md on GitHub

Every JSON example below was captured by a script, not typed by hand. The script wrote the synthetic estate from tests/mcp/fixtures/sample_estate.py (an AWS organization with a prod and a shared-services account, an external vendor account, a few Azure and GCP assets, 44 assets, 56 edges, 12 findings, one of them suppressed) and loaded it with:

from cloudg.config import CloudGConfig
from cloudg.mcp.layer import CloudGMCPLayer
from cloudg.mcp.state import Workspace

ws = Workspace(CloudGConfig(), allowed_roots=[estate], output_dir=estate / "out")
layer = CloudGMCPLayer(policy="open", workspace=ws)
result = await layer.call_tool("load_dataset", {"path": str(estate / "inventory"), "name": "sample"})

The open policy applies no transforms, so the examples show raw tool output. Under the default standard policy, secrets are redacted and every result carries an extra cloudg/transforms entry in _meta. A few things were changed for print:

  • Arrays are cut to the first two or three items, followed by a marker such as "... 5 more"; count maps keep five keys plus "...": "N more". The markers are added for this document; the tool returned everything.
  • Long strings end in ... where they were cut.
  • <estate> stands for the absolute path of the sample-estate directory on the capture machine.
  • Error examples are shown as one object holding the tool name, the arguments, and the error result's text (content[0].text) and _meta.
  • Calls run in document order against one workspace, so some results depend on earlier calls (for example the dataset version grows after a mutation). Where that matters the text says so. The sample dataset was loaded again, unmodified, at the start of the Compliance, Ontology, Export, Live, Meta and Privacy sections, so the suppressions and the ingested finding of the Findings section do not show up there. The resource, completion and prompt examples used a fresh workspace holding sample, its snapshot baseline and after, and the recipes a fresh sample.
  • The script also wrote the inputs some examples need: scans/prowler-asff.json (one Prowler ASFF record for sg-web), scans/prowler-ocsf.json (one Prowler OCSF record) and after/, a copy of the inventory edited as described under diff_datasets.
  • Timestamps (loaded_at, detected_at, audit ts), cursors and pseudonyms differ from run to run.

The live tools (map_inventory, collect_assets, run_scanners, run_pipeline) were run against a stub: cloudg.api.CloudGEngine was replaced by the FakeEngine class from tests/mcp/test_catalog_export_live_meta.py and cloudg.mcp.catalog.live.credential_problems was patched to return {}. The workspace kept its LiveOperationGuard with the default settings; its cooldowns were reset between examples that are not about the guard, and the rate_limit_status example got a fresh guard. Their results show the real envelope and progress notifications the layer produces, but the inventory inside them is the sample estate, not a cloud account. The credential failure example under map_inventory is real: it ran the actual AWS credential check against an empty AWS config with the metadata service disabled.

To repeat any example yourself, use the in-process CLI (see MCP.md for every option):

cloudg mcp call find_assets --policy open --dataset sample=./inventory \
    --args '{"tag": "data=pii", "fields": ["name", "type"]}'
cloudg mcp read cloudg://findings/summary --policy open --dataset sample=./inventory