# cloud-knowledge: calls each hyperscaler's hosted knowledge server over MCP. A query is only ever built from the # fixed lists below, so a customer's name or resource can't reach a third party. import asyncio import boto3 from botocore.auth import SigV4Auth from botocore.awsrequest import AWSRequest 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): url = KNOWLEDGE_SERVERS[provider]["url"] headers = {"Accept": "application/json, text/event-stream", "Content-Type": "application/json"} if session: headers["Mcp-Session-Id"] = session if provider == "gcp": headers["X-Goog-Api-Key"] = connection.get("google_api_key", "") content = json.dumps(body) if provider == "aws": 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]) -> Optional[str]: response = await _knowledge_post(provider, connection, { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "cloud-knowledge", "version": "0.1.0"}}}) return response.headers.get("mcp-session-id") async def _knowledge_tools(provider: str, connection: Dict[str, Any], session: Optional[str] = None) -> List[Dict[str, Any]]: session = session or await _knowledge_session(provider, connection) response = await _knowledge_post(provider, connection, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session) 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) -> List[Dict[str, Any]]: session = await _knowledge_session(provider, connection) name = KNOWLEDGE_SERVERS[provider]["tool"] tools = {t.get("name"): t for t in await _knowledge_tools(provider, connection, session)} 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) 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