- Scripts to run workflows from a YAML context or run inputs (kab_run_workflow.py, with --input name=@file), store per-project discovery connections, bootstrap agent MCP keys, refresh the KAB token, publish reports and build estate snapshots. - Hyperscaler discovery servers extended in place; cloud-knowledge folded into them. - deploy/crucible-kab-dev.yaml: the Discovery package agent and the Assessment agents. - Platform issue write-ups and current-wiring notes under docs/platform-issues/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
135 lines
7.4 KiB
Python
135 lines
7.4 KiB
Python
# Well-Architected guidance: calls each hyperscaler's hosted knowledge server over MCP. Inlined into the
|
|
# azure-discovery and gcp-discovery servers (cloud-knowledge, which also used it, was retired on 2026-11-04). A query is only ever built from the fixed lists below, so a
|
|
# customer's name or resource can't reach a third party. boto3 is imported only for AWS, so the other servers don't
|
|
# need it.
|
|
import asyncio
|
|
|
|
KNOWLEDGE_SERVERS = {
|
|
"azure": {"url": "https://learn.microsoft.com/api/mcp", "tool": "microsoft_docs_search",
|
|
"framework": "Azure Well-Architected Framework"},
|
|
"aws": {"url": "https://aws-mcp.eu-west-1.api.aws/mcp", "tool": "aws___search_documentation",
|
|
"framework": "AWS Well-Architected Framework"},
|
|
"gcp": {"url": "https://developerknowledge.googleapis.com/mcp", "tool": "search_documents",
|
|
"framework": "Google Cloud Well-Architected Framework"},
|
|
}
|
|
KNOWLEDGE_PILLARS = ("reliability", "security", "cost", "operations", "performance", "sustainability")
|
|
KNOWLEDGE_TOPICS = (
|
|
"landing zone", "resource organization", "identity and access", "network segmentation", "hybrid connectivity",
|
|
"encryption", "logging and monitoring", "backup and recovery", "disaster recovery", "high availability",
|
|
"scaling", "kubernetes", "containers", "virtual machines", "databases", "storage", "serverless", "governance",
|
|
"policy enforcement", "tagging", "cost allocation", "migration", "incident response", "patching",
|
|
)
|
|
KNOWLEDGE_MAX_TEXT = 4000
|
|
|
|
|
|
def _knowledge_client():
|
|
return get_upstream_client("knowledge", lambda c: httpx.AsyncClient(timeout=60, follow_redirects=False))
|
|
|
|
|
|
def _knowledge_message(response) -> Dict[str, Any]:
|
|
"""The JSON-RPC reply, whether it came back as JSON or as a server-sent event."""
|
|
if "text/event-stream" in response.headers.get("content-type", ""):
|
|
lines = [line[5:].strip() for line in response.text.splitlines() if line.startswith("data:")]
|
|
return json.loads(lines[-1]) if lines else {}
|
|
return response.json()
|
|
|
|
|
|
async def _knowledge_post(provider: str, connection: Dict[str, Any], body: Dict[str, Any],
|
|
session: Optional[str] = None, auth: Optional[Dict[str, str]] = None):
|
|
"""auth: headers a discovery server supplies from its own connection (gcp-discovery's OAuth token), used in
|
|
place of the stored API key."""
|
|
url = KNOWLEDGE_SERVERS[provider]["url"]
|
|
headers = {"Accept": "application/json, text/event-stream", "Content-Type": "application/json"}
|
|
if session:
|
|
headers["Mcp-Session-Id"] = session
|
|
if auth:
|
|
headers.update(auth)
|
|
elif provider == "gcp":
|
|
headers["X-Goog-Api-Key"] = connection.get("google_api_key", "")
|
|
content = json.dumps(body)
|
|
if provider == "aws":
|
|
import boto3
|
|
from botocore.auth import SigV4Auth
|
|
from botocore.awsrequest import AWSRequest
|
|
|
|
def sign():
|
|
credentials = boto3.Session(aws_access_key_id=connection.get("aws_access_key_id"),
|
|
aws_secret_access_key=connection.get("aws_secret_access_key")).get_credentials()
|
|
request = AWSRequest(method="POST", url=url, data=content, headers=headers)
|
|
SigV4Auth(credentials, "aws-mcp", "eu-west-1").add_auth(request)
|
|
return dict(request.headers)
|
|
|
|
headers = await asyncio.to_thread(sign)
|
|
response = await _with_backoff(lambda: _knowledge_client().post(url, content=content, headers=headers))
|
|
response.raise_for_status()
|
|
return response
|
|
|
|
|
|
async def _knowledge_session(provider: str, connection: Dict[str, Any], auth: Optional[Dict[str, str]] = None) -> Optional[str]:
|
|
response = await _knowledge_post(provider, connection, {
|
|
"jsonrpc": "2.0", "id": 1, "method": "initialize",
|
|
"params": {"protocolVersion": "2025-06-18", "capabilities": {},
|
|
"clientInfo": {"name": "kab-cp1-discovery", "version": "0.1.0"}}}, auth=auth)
|
|
return response.headers.get("mcp-session-id")
|
|
|
|
|
|
async def _knowledge_tools(provider: str, connection: Dict[str, Any], session: Optional[str] = None,
|
|
auth: Optional[Dict[str, str]] = None) -> List[Dict[str, Any]]:
|
|
session = session or await _knowledge_session(provider, connection, auth)
|
|
response = await _knowledge_post(provider, connection, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session, auth)
|
|
return _knowledge_message(response).get("result", {}).get("tools", [])
|
|
|
|
|
|
def _knowledge_argument(tool: Dict[str, Any]) -> str:
|
|
"""The search tool's query argument. Vendors name it differently and may change it, so it's read from the tool."""
|
|
schema = tool.get("inputSchema", {})
|
|
properties = schema.get("properties", {})
|
|
for name in list(schema.get("required", [])) + list(properties):
|
|
if properties.get(name, {}).get("type") == "string":
|
|
return name
|
|
return "query"
|
|
|
|
|
|
async def _knowledge_search(provider: str, connection: Dict[str, Any], query: str,
|
|
auth: Optional[Dict[str, str]] = None) -> List[Dict[str, Any]]:
|
|
session = await _knowledge_session(provider, connection, auth)
|
|
name = KNOWLEDGE_SERVERS[provider]["tool"]
|
|
tools = {t.get("name"): t for t in await _knowledge_tools(provider, connection, session, auth)}
|
|
if name not in tools:
|
|
raise LookupError(f"{provider} no longer offers {name}")
|
|
response = await _knowledge_post(provider, connection, {
|
|
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
|
|
"params": {"name": name, "arguments": {_knowledge_argument(tools[name]): query}}}, session, auth)
|
|
message = _knowledge_message(response)
|
|
results = []
|
|
for part in message.get("result", {}).get("content", []):
|
|
if part.get("type") != "text":
|
|
continue
|
|
try:
|
|
parsed = json.loads(part["text"])
|
|
except ValueError:
|
|
parsed = {"content": part["text"]}
|
|
found = parsed.get("results", parsed) if isinstance(parsed, dict) else parsed
|
|
for item in found if isinstance(found, list) else [found]:
|
|
if isinstance(item, dict):
|
|
results.append({"title": item.get("title"), "url": item.get("contentUrl") or item.get("url"),
|
|
"text": str(item.get("content") or item.get("text") or "")[:KNOWLEDGE_MAX_TEXT]})
|
|
return results
|
|
|
|
|
|
async def _knowledge_tool(provider: str, tool: str, arguments: Dict[str, Any], connection: Dict[str, Any],
|
|
auth: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
|
|
"""One provider's `<provider>_search_well_architected` tool: fixed pillar and topic in, guidance excerpts out."""
|
|
pillar, topic = arguments.get("pillar"), arguments.get("topic")
|
|
if pillar not in KNOWLEDGE_PILLARS:
|
|
return _refuse("invalid_argument", "pillar must be one of: " + ", ".join(KNOWLEDGE_PILLARS))
|
|
if topic not in KNOWLEDGE_TOPICS:
|
|
return _refuse("invalid_argument", "topic must be one of: " + ", ".join(KNOWLEDGE_TOPICS))
|
|
query = f"{KNOWLEDGE_SERVERS[provider]['framework']} {pillar} {topic}"
|
|
try:
|
|
results = await _knowledge_search(provider, connection, query, auth)
|
|
except Exception as error:
|
|
return _upstream_failed(provider, error)
|
|
return {"success": True, "data": {"provider": provider, "pillar": pillar, "topic": topic, "results": results,
|
|
"collected_at": _collected_at(), "evidence_ref": _evidence_ref(tool, arguments, results)}}
|