feat: add local tools and read-only remote MCP servers

Increment 6 of .scratch/solution-architect-agent/spec.md, test-first.

- app/tools/mcp.py: MCP client and catalog exposing only allowlisted,
  readOnlyHint tools as framework-neutral ToolSpecs; unreachable servers
  and failed calls become discovery gaps; ADC auth with quota project.
- app/tools/local.py: Mermaid structure check and Terraform fmt,
  validate and plan in a scratch copy; apply is never constructed.
- Tool factory gives roles their named local tools and bundle MCP
  servers; pillar advisors get general-tier documentation tools.
- providers/gcp.yaml: 42 allowlisted tools reviewed against live
  tools/list of 12 Google Cloud MCP servers (snapshot in
  providers/reviews/), excluding data-reading and secret-capable tools.
- scripts/list-mcp-tools.py, docs/operations/mcp-access.md (IAM deny
  policy, service account roles), cloud-discovery and iac-validation
  Skills, MCP and Terraform settings, pytest asyncio auto mode.
- 31 new tests; full suite 189 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-09-16 10:14:05 +01:00
parent f040493583
commit ed104e5697
37 changed files with 2302 additions and 65 deletions

View File

@@ -0,0 +1,38 @@
---
name: cloud-discovery
description: >-
Discovers and documents the current state of a workload's existing cloud
environment through the Cloud provider's read-only MCP discovery tools. Use
when requirements discovery needs the as-is architecture of resources that
already run in the user's cloud project or account.
metadata:
scope: requirements-discovery
---
# Cloud discovery
Describe what actually exists, so requirements rest on facts rather than recollection.
## Before you discover
Your discovery tools read the user's live cloud environment. The first call may pause the Execution to ask the user's permission. When permission is refused, work only from what the user tells you.
Ask the user which project, subscription or account and which regions hold the workload, unless the request already says. Discover only there.
## Steps
1. **Inventory first.** Use the broadest inventory tool available (an asset inventory or project search) to list the resource types and counts in scope.
2. **Detail what matters.** For each resource type that belongs to the workload, call the product's list and get tools for configuration: sizes, regions and zones, scaling, networking, identities and their roles.
3. **Map relationships.** Connect compute to its data stores, messaging, load balancers and identities, from configuration you have read, not from names alone.
4. **Record gaps.** When a tool reports a discovery gap (a server that's unavailable, an API that isn't enabled, a permission that's missing), list it under `Assumptions / discovery gaps` with the resource type it leaves unknown.
## Writing the current state
Under the `Current state` heading, give:
- a component inventory table: component, resource type, location, key configuration
- the relationships between components as a short list
- observed operational signals, such as alert policies and dashboards, when discovered
- `Assumptions / discovery gaps`
Report what exists, not what should change; recommendations belong to later Deliverables. Never include secrets, credentials, object contents or database rows, even when a tool returns them.

View File

@@ -0,0 +1,39 @@
---
name: iac-validation
description: >-
Checks Terraform infrastructure-as-code without provisioning anything, using
the local terraform_fmt, terraform_validate and terraform_plan tools. Use when
writing deployment guidance or validating it before deployment.
metadata:
scope: deployment-guidance validation
---
# IaC validation
Every check runs on a scratch copy of the files you pass. Nothing is applied, and no state is written.
## Tools
- `terraform_fmt(files)`: returns the files formatting changed. Replace your copies with the returned content.
- `terraform_validate(files)`: runs `init -backend=false` and `validate` offline. It reports syntax errors, unknown references, missing variables and invalid arguments.
- `terraform_plan(files, variables)`: previews the changes against the live cloud environment. It reads live state, so the first call may pause for the user's permission. Pass every variable the configuration requires.
## When writing deployment guidance
1. Run `terraform_fmt`, then `terraform_validate`, on the complete set of files you will attach.
2. Fix every error and run both again, until `terraform_validate` passes.
3. Attach the formatted files.
## When validating deployment guidance
1. Run `terraform_validate` on the attached files, and report its verdict and output.
2. When permission to read the live environment is granted, run `terraform_plan` with the variable values from the requirements, or clearly marked placeholders. Summarise the resources to add, change and destroy, and flag any destroy or replace.
3. When a check can't run (a missing CLI, a refused permission or a provider download failure), give the user the exact commands to run themselves:
```bash
terraform init -backend=false
terraform validate
terraform plan -lock=false -var-file=<your.tfvars>
```
Never suggest `terraform apply` as part of validation.