Files
gcp_solution_architecture_a…/app/execution/pillars.py
Jonathan Boniface ed104e5697 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>
2026-09-16 10:14:05 +01:00

112 lines
3.5 KiB
Python

"""The design advisor's fan-out to one advisor per architecture-framework pillar.
Pillar advice is working material for the design recommendations Deliverable, not a
Deliverable itself, so it never touches the Ledger.
"""
from __future__ import annotations
import asyncio
import dataclasses
from collections.abc import Mapping, Sequence
from app.agents.runtime import (
AgentRuntime,
AgentTask,
RoleSpec,
Submitted,
ToolResult,
ToolSpec,
)
CONSULT_TOOL = "consult_pillar_advisors"
def pillar_consultation_tool(
runtime: AgentRuntime,
advisor: RoleSpec,
pillar_skills: Mapping[str, str],
extra_tools: Sequence[ToolSpec] = (),
) -> ToolSpec:
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill."""
async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult:
chosen = list(pillars) if pillars else list(pillar_skills)
unknown = [pillar for pillar in chosen if pillar not in pillar_skills]
if unknown:
return ToolResult(
f"Refused: unknown pillars {', '.join(unknown)}; "
f"choose from {', '.join(pillar_skills)}"
)
results = await asyncio.gather(
*(
_advise(
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
)
for pillar in chosen
)
)
return ToolResult("\n\n".join(results))
return ToolSpec(
CONSULT_TOOL,
"Get guidance from one advisor per architecture-framework pillar, in parallel. "
"Give a brief with the workload, its requirements and the selected products.",
{
"type": "object",
"properties": {
"brief": {"type": "string"},
"pillars": {
"type": "array",
"items": {"type": "string", "enum": list(pillar_skills)},
},
},
"required": ["brief"],
},
consult,
)
async def _advise(
runtime: AgentRuntime,
advisor: RoleSpec,
pillar: str,
skill: str,
brief: str,
extra_tools: Sequence[ToolSpec],
) -> str:
role = dataclasses.replace(advisor, skills=(skill,))
task = AgentTask(
role=advisor.name,
prompt=f"Advise on the {pillar} pillar for this workload.",
context={"pillar": pillar, "brief": brief},
)
try:
outcome = await runtime.run(role, task, [_submit_advice_tool(), *extra_tools])
except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others
return f"## {pillar}\n\nNo guidance: the advisor failed ({exc})."
if isinstance(outcome, Submitted):
return f"## {pillar}\n\n{outcome.content.strip()}"
return (
f"## {pillar}\n\nNo guidance: the advisor ended with {type(outcome).__name__}."
)
def _submit_advice_tool() -> ToolSpec:
async def submit_advice(content: str) -> ToolResult:
if not content.strip():
return ToolResult("Not submitted: the advice is empty.")
return ToolResult("Advice submitted.", Submitted(content))
return ToolSpec(
"submit_advice",
"Submit your pillar recommendations as markdown. Ends your turn.",
{
"type": "object",
"properties": {"content": {"type": "string"}},
"required": ["content"],
},
submit_advice,
tier="execution",
)