# 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 `_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)}}