#!/usr/bin/env python3 """Write the three .server.yaml definitions from the tables below, then render with ../../../scripts/render_mcp_server.py. One server per hyperscaler, each carrying the tool set of gcp_solution_architecture_agent (its providers/gcp.yaml), so the agent never depends on the shared servers in the repository's root mcp-servers/. Usage: python3 build_definitions.py """ import ast from pathlib import Path import yaml HERE = Path(__file__).resolve().parent SHARED = "../../../mcp-servers/_common" PAGING = [ {"name": "page_size", "type": "integer", "description": "Items per page, up to 200. Default 50.", "required": False}, {"name": "page_token", "type": "string", "description": "next_page_token from the previous reply.", "required": False}, ] AWS_WHERE = [ {"name": "account_id", "type": "string", "description": "A member account of the connection.", "required": False}, {"name": "region", "type": "string", "description": "One of the connection's regions; the first by default.", "required": False}, ] def param(name, description, kind="string", required=True): return {"name": name, "type": kind, "description": description, "required": required} def tool(name, description, body, parameters=()): return {"name": name, "display_name": name.replace("_", " ").capitalize(), "description": description, "parameters": list(parameters), "ai_implementation": f"async def {name}(arguments: Dict[str, Any]) -> Dict[str, Any]:\n{body}\n"} def gcp(): source = (HERE / "_support" / "gcp_tools.py").read_text() catalog = next(ast.literal_eval(n.value) for n in ast.parse(source).body if isinstance(n, ast.Assign) and n.targets[0].id == "GCP_MCP_SERVERS") tools = [ tool("gcp_check_connection", "Test the stored connection: sign in and open the resource manager server.", ' try:\n await _gcp_mcp_session("resource_manager")\n except Exception as error:\n' ' return {"ok": False, "message": _upstream_failed("gcp", error)["error"]["message"]}\n' ' return {"ok": True, "message": "Signed in and reached Google\'s hosted servers."}'), tool("gcp_describe_tool", "Read a hosted tool's live description and argument schema, before calling it.", " return await _gcp_describe(arguments)", [param("server", "The hosted server, such as compute."), param("tool", "The hosted tool, such as list_instances.")]), ] for server, entry in catalog.items(): for name in entry["allow"]: tools.append(tool(f"gcp_{server}_{name}", f"Google's {name} on its {server} MCP server, read-only. Call gcp_describe_tool for its arguments.", f' return await _gcp_forward("gcp_{server}_{name}", "{server}", "{name}", arguments)', [param("tool_arguments", "The hosted tool's arguments.", "object", False)])) return { "server_id": "sa-gcp-cloud", "name": "Solution Architecture Google Cloud", "description": "Google Cloud documentation and read-only estate tools for the Solution Architecture agent, " "through Google's hosted MCP servers.", "version": "0.1.0", "port": 8115, "verify_tool": "gcp_check_connection", "shared_code": [f"{SHARED}/tool_support.py", f"{SHARED}/gcp_support.py", "_support/docs_log.py", "_support/gcp_tools.py"], "extra_requirements": ["google-auth==2.62.0", "requests==2.32.5"], "connection_fields": [ {"name": "service_account_json", "title": "Service account key", "description": "The read-only service account's JSON key.", "required": True, "secret": True}, {"name": "scope_root", "title": "Scope root", "description": "organizations/, folders/ or projects/.", "required": True, "secret": False}, {"name": "quota_project", "title": "Quota project", "description": "Sent as X-Goog-User-Project. Optional.", "required": False, "secret": False}, {"name": "docs_api_key", "title": "Documentation API key", "description": "Developer Knowledge API key. Without it, the service account signs in.", "required": False, "secret": True}, ], "tools": tools, } def azure(): sub = param("subscription_id", "Needed when the connection's scope is a management group.", required=False) rid = param("resource_id", "The full ARM resource id.") tools = [ tool("azure_check_connection", "Test the stored connection: sign in and read the scope root. Returns no customer data.", ' try:\n await _azure_graph("ResourceContainers | limit 1", 1)\n except Exception as error:\n' ' return {"ok": False, "message": _upstream_failed("azure", error)["error"]["message"]}\n' ' return {"ok": True, "message": "Signed in and read the scope root."}'), tool("azure_search_documents", "Search Microsoft Learn in free text. Queries are sent as written and logged.", ' return await _docs_search("azure", "azure_search_documents", arguments, {})', [param("query", "What to look up. Keep client detail out.")]), tool("azure_get_documents", "Fetch one Microsoft Learn page by URL.", ' return await _docs_read("azure", "azure_get_documents", arguments, {}, "microsoft_docs_fetch", "url")', [param("url", "A learn.microsoft.com URL.")]), tool("azure_analyze_access", "List role assignments, optionally for one principal or below one scope.", ' return await _azure_access("azure_analyze_access", arguments)', [param("principal_id", "An object id.", required=False), param("scope", "An ARM scope.", required=False), *PAGING]), tool("azure_list_instance_attached_disks", "List the disks attached to one virtual machine.", ' return await _azure_attached_disks("azure_list_instance_attached_disks", arguments)', [rid, *PAGING]), tool("azure_list_node_pools", "List AKS node pools.", ' return await _azure_node_pools("azure_list_node_pools", arguments)', PAGING), ] graph = [ ("azure_search_subscriptions", "ResourceContainers", ["microsoft.resources/subscriptions"], "subscriptions"), ("azure_list_instances", "Resources", ["microsoft.compute/virtualmachines"], "virtual machines"), ("azure_list_instance_group_managers", "Resources", ["microsoft.compute/virtualmachinescalesets"], "scale sets"), ("azure_list_instance_templates", "Resources", ["microsoft.resources/templatespecs", "microsoft.compute/galleries/images"], "template specs and gallery images"), ("azure_list_disks", "Resources", ["microsoft.compute/disks"], "managed disks"), ("azure_list_reservations", "Resources", ["microsoft.compute/capacityreservationgroups"], "capacity reservation groups"), ("azure_list_clusters", "Resources", ["microsoft.containerservice/managedclusters"], "AKS clusters"), ("azure_list_services", "Resources", ["microsoft.app/containerapps", "microsoft.web/sites"], "Container Apps and App Service apps"), ("azure_list_sql_instances", "Resources", ["microsoft.sql/servers", "microsoft.sql/managedinstances", "microsoft.dbforpostgresql/flexibleservers", "microsoft.dbformysql/flexibleservers"], "SQL, PostgreSQL and MySQL servers"), ("azure_list_buckets", "Resources", ["microsoft.storage/storageaccounts"], "storage accounts"), ("azure_list_topics", "Resources", ["microsoft.servicebus/namespaces", "microsoft.eventhub/namespaces", "microsoft.eventgrid/topics"], "Service Bus, Event Hubs and Event Grid topics"), ("azure_list_roles", "AuthorizationResources", ["microsoft.authorization/roledefinitions"], "role definitions"), ("azure_list_alert_policies", "Resources", ["microsoft.insights/metricalerts", "microsoft.insights/activitylogalerts", "microsoft.insights/scheduledqueryrules"], "alert rules"), ("azure_list_dashboards", "Resources", ["microsoft.portal/dashboards"], "dashboards"), ("azure_list_connectivity_tests", "Resources", ["microsoft.network/networkwatchers/connectionmonitors"], "connection monitors"), ] for name, table, types, what in graph: tools.append(tool(name, f"List {what}.", f' return await _azure_list("{name}", arguments, "{table}", {types!r})', PAGING)) for name, table, types, what in [ ("azure_get_instance_basic_info", "Resources", ["microsoft.compute/virtualmachines"], "one virtual machine"), ("azure_get_instance_group_manager_basic_info", "Resources", ["microsoft.compute/virtualmachinescalesets"], "one scale set"), ("azure_get_instance_template_properties", "Resources", ["microsoft.resources/templatespecs", "microsoft.compute/galleries/images"], "one template spec or gallery image"), ("azure_get_disk_basic_info", "Resources", ["microsoft.compute/disks"], "one disk"), ("azure_get_cluster", "Resources", ["microsoft.containerservice/managedclusters"], "one AKS cluster"), ("azure_get_service", "Resources", ["microsoft.app/containerapps", "microsoft.web/sites"], "one app"), ("azure_get_sql_instance", "Resources", ["microsoft.sql/servers", "microsoft.sql/managedinstances", "microsoft.dbforpostgresql/flexibleservers", "microsoft.dbformysql/flexibleservers"], "one database server"), ("azure_get_topic", "Resources", ["microsoft.servicebus/namespaces", "microsoft.eventhub/namespaces", "microsoft.eventgrid/topics"], "one messaging resource"), ("azure_get_role", "AuthorizationResources", ["microsoft.authorization/roledefinitions"], "one role definition"), ("azure_get_alert_policy", "Resources", ["microsoft.insights/metricalerts", "microsoft.insights/activitylogalerts", "microsoft.insights/scheduledqueryrules"], "one alert rule"), ("azure_get_connectivity_test", "Resources", ["microsoft.network/networkwatchers/connectionmonitors"], "one connection monitor"), ]: tools.append(tool(name, f"Read {what}.", f' return await _azure_get("{name}", arguments, "{table}", {types!r})', [rid])) tools += [ tool("azure_list_assets", "List every resource in scope, or one resource type.", ' kind = arguments.get("resource_type")\n if kind and not re.fullmatch(r"[A-Za-z0-9./]+", str(kind)):\n return _refuse("invalid_argument", "resource_type must be an ARM type")\n' ' where = f" | where type =~ \'{kind}\'" if kind else ""\n' ' return await _azure_page("azure_list_assets", arguments, f"Resources{where} | project id, name, type, location, resourceGroup, subscriptionId, tags | order by id asc")', [param("resource_type", "An ARM type.", required=False), *PAGING]), tool("azure_get_node_pool", "Read one AKS node pool.", ' return await _azure_resource_arm("azure_get_node_pool", arguments, f"/agentPools/{arguments.get(\'pool\')}", {"api-version": "2024-05-01"}) if re.fullmatch(r"[A-Za-z0-9]+", str(arguments.get("pool"))) else _refuse("invalid_argument", "pool must be a pool name")', [rid, param("pool", "The node pool's name.")]), tool("azure_list_commitments", "List reserved capacity orders, Azure's committed-use discounts.", ' return await _azure_arm("azure_list_commitments", arguments, "/providers/Microsoft.Capacity/reservationOrders", {"api-version": "2022-11-01"})', PAGING), tool("azure_get_k8s_version", "List the Kubernetes versions AKS offers in one location.", ' location = str(arguments.get("location") or "")\n if not re.fullmatch(r"[a-z0-9]+", location):\n return _refuse("invalid_argument", "location must be an Azure region name")\n' ' return await _azure_subscription_arm("azure_get_k8s_version", arguments, f"/providers/Microsoft.ContainerService/locations/{location}/kubernetesVersions", {"api-version": "2024-05-01"})', [param("location", "An Azure region, such as uksouth."), sub]), tool("azure_list_subscriptions", "List Event Grid event subscriptions.", ' return await _azure_subscription_arm("azure_list_subscriptions", arguments, "/providers/Microsoft.EventGrid/eventSubscriptions", {"api-version": "2022-06-15"})', [sub, *PAGING]), tool("azure_list_deny_policies", "List deny assignments.", ' return await _azure_subscription_arm("azure_list_deny_policies", arguments, "/providers/Microsoft.Authorization/denyAssignments", {"api-version": "2022-04-01"})', [sub, *PAGING]), tool("azure_list_metric_descriptors", "List the metrics one resource publishes.", ' return await _azure_resource_arm("azure_list_metric_descriptors", arguments, "/providers/Microsoft.Insights/metricDefinitions", {"api-version": "2018-01-01"})', [rid]), tool("azure_list_timeseries", "Read metric values for one resource.", ' wanted = {k: arguments.get(k) for k in ("metricnames", "timespan", "interval", "aggregation") if arguments.get(k)}\n' ' if "metricnames" not in wanted or "timespan" not in wanted:\n return _refuse("invalid_argument", "metricnames and timespan are required")\n' ' return await _azure_resource_arm("azure_list_timeseries", arguments, "/providers/Microsoft.Insights/metrics", {"api-version": "2018-01-01", **wanted})', [rid, param("metricnames", "Comma-separated metric names."), param("timespan", "ISO 8601 interval, start/end."), param("interval", "ISO 8601 duration, such as PT1H.", required=False), param("aggregation", "Average, Total, Maximum, Minimum or Count.", required=False)]), ] return { "server_id": "sa-azure-cloud", "name": "Solution Architecture Azure", "description": "Azure documentation and read-only estate tools for the Solution Architecture agent, through " "Microsoft Learn, Resource Graph and ARM.", "version": "0.1.0", "port": 8116, "verify_tool": "azure_check_connection", "shared_code": [f"{SHARED}/tool_support.py", f"{SHARED}/azure_support.py", f"{SHARED}/knowledge_support.py", "_support/docs_log.py", "_support/docs_support.py", "_support/azure_tools.py"], "extra_requirements": ["boto3==1.43.122"], "connection_fields": [ {"name": "tenant_id", "title": "Tenant id", "description": "The Entra tenant id.", "required": False, "secret": False}, {"name": "client_id", "title": "Client id", "description": "The app registration's id.", "required": False, "secret": False}, {"name": "client_secret", "title": "Client secret", "description": "The client secret.", "required": False, "secret": True}, {"name": "scope_root", "title": "Scope root", "description": "managementGroups/ or subscriptions/.", "required": True, "secret": False}, {"name": "cloud", "title": "Cloud", "description": "public, usgov or china. Optional.", "required": False, "secret": False}, ], "tools": tools, } def aws(): where = [*AWS_WHERE, *PAGING] aws_id = lambda name, what: param(name, what) # noqa: E731 listing = [ ("aws_search_projects", "the organisation's accounts", ("organizations", "list_accounts", "Accounts", "NextToken", "NextToken", {})), ("aws_list_assets", "tagged resources", ("resourcegroupstaggingapi", "get_resources", "ResourceTagMappingList", "PaginationToken", "PaginationToken", {})), ("aws_list_instances", "EC2 instances", ("ec2", "describe_instances", "Reservations", "NextToken", "NextToken", {})), ("aws_list_instance_group_managers", "Auto Scaling groups", ("autoscaling", "describe_auto_scaling_groups", "AutoScalingGroups", "NextToken", "NextToken", {})), ("aws_list_instance_templates", "launch templates", ("ec2", "describe_launch_templates", "LaunchTemplates", "NextToken", "NextToken", {})), ("aws_list_disks", "EBS volumes", ("ec2", "describe_volumes", "Volumes", "NextToken", "NextToken", {})), ("aws_list_reservations", "capacity reservations", ("ec2", "describe_capacity_reservations", "CapacityReservations", "NextToken", "NextToken", {})), ("aws_list_commitments", "Savings Plans", ("savingsplans", "describe_savings_plans", "savingsPlans", "nextToken", "nextToken", {})), ("aws_list_clusters", "EKS clusters", ("eks", "list_clusters", "clusters", "nextToken", "nextToken", {})), ("aws_list_services", "App Runner services", ("apprunner", "list_services", "ServiceSummaryList", "NextToken", "NextToken", {})), ("aws_list_functions", "Lambda functions", ("lambda", "list_functions", "Functions", "Marker", "NextMarker", {})), ("aws_list_sql_instances", "RDS instances", ("rds", "describe_db_instances", "DBInstances", "Marker", "Marker", {})), ("aws_list_buckets", "S3 buckets", ("s3", "list_buckets", "Buckets", "ContinuationToken", "ContinuationToken", {})), ("aws_list_topics", "SNS topics", ("sns", "list_topics", "Topics", "NextToken", "NextToken", {})), ("aws_list_subscriptions", "SNS subscriptions", ("sns", "list_subscriptions", "Subscriptions", "NextToken", "NextToken", {})), ("aws_list_roles", "IAM roles", ("iam", "list_roles", "Roles", "Marker", "Marker", {})), ("aws_list_deny_policies", "service control policies", ("organizations", "list_policies", "Policies", "NextToken", "NextToken", {"Filter": "SERVICE_CONTROL_POLICY"})), ("aws_list_alert_policies", "CloudWatch metric alarms", ("cloudwatch", "describe_alarms", "MetricAlarms", "NextToken", "NextToken", {})), ("aws_list_dashboards", "CloudWatch dashboards", ("cloudwatch", "list_dashboards", "DashboardEntries", "NextToken", "NextToken", {})), ("aws_list_metric_descriptors", "CloudWatch metrics", ("cloudwatch", "list_metrics", "Metrics", "NextToken", "NextToken", {})), ("aws_list_connectivity_tests", "Reachability Analyzer paths", ("ec2", "describe_network_insights_paths", "NetworkInsightsPaths", "NextToken", "NextToken", {})), ] tools = [ tool("aws_check_connection", "Test the stored connection: assume the role and read its identity. Returns no customer data.", ' try:\n await _aws_call(arguments, "sts", "get_caller_identity")\n except Exception as error:\n' ' return {"ok": False, "message": _upstream_failed("aws", error)["error"]["message"]}\n' ' return {"ok": True, "message": "Assumed the role."}'), tool("aws_search_documents", "Search AWS documentation in free text. Queries are sent as written and logged.", ' return await _docs_search("aws", "aws_search_documents", arguments, _aws_docs_connection())', [param("query", "What to look up. Keep client detail out.")]), tool("aws_get_documents", "Read one AWS documentation page by URL.", ' return await _docs_read("aws", "aws_get_documents", arguments, _aws_docs_connection(), "aws___read_documentation", "url", _aws_docs_request)', [param("url", "A docs.aws.amazon.com URL.")]), ] for name, what, entry in listing: tools.append(tool(name, f"List {what}.", f' return await _aws_list("{name}", arguments, {entry!r})', where)) tools += [ tool("aws_list_node_pools", "List one EKS cluster's node groups.", " return await _aws_list(\"aws_list_node_pools\", arguments, (\"eks\", \"list_nodegroups\", \"nodegroups\", \"nextToken\", \"nextToken\", {}), [(\"clusterName\", \"cluster\")])", [aws_id("cluster", "The cluster's name."), *where]), tool("aws_list_instance_attached_disks", "List the EBS volumes attached to one instance.", ' instance = arguments.get("instance_id")\n if not instance:\n return _refuse("invalid_argument", "instance_id is required")\n' ' return await _aws_list("aws_list_instance_attached_disks", arguments, ("ec2", "describe_volumes", "Volumes", "NextToken", "NextToken", {"Filters": [{"Name": "attachment.instance-id", "Values": [str(instance)]}]}))', [aws_id("instance_id", "The instance id."), *where]), ] for name, what, service, operation, request, parameters in [ ("aws_get_instance_basic_info", "one EC2 instance", "ec2", "describe_instances", '{"InstanceIds": [arguments.get("instance_id")]}', [aws_id("instance_id", "The instance id.")]), ("aws_get_instance_group_manager_basic_info", "one Auto Scaling group", "autoscaling", "describe_auto_scaling_groups", '{"AutoScalingGroupNames": [arguments.get("name")]}', [aws_id("name", "The group's name.")]), ("aws_get_instance_template_properties", "a launch template's versions", "ec2", "describe_launch_template_versions", '{"LaunchTemplateId": arguments.get("template_id")}', [aws_id("template_id", "The template id.")]), ("aws_get_disk_basic_info", "one EBS volume", "ec2", "describe_volumes", '{"VolumeIds": [arguments.get("volume_id")]}', [aws_id("volume_id", "The volume id.")]), ("aws_get_cluster", "one EKS cluster", "eks", "describe_cluster", '{"name": arguments.get("name")}', [aws_id("name", "The cluster's name.")]), ("aws_get_node_pool", "one EKS node group", "eks", "describe_nodegroup", '{"clusterName": arguments.get("cluster"), "nodegroupName": arguments.get("name")}', [aws_id("cluster", "The cluster's name."), aws_id("name", "The node group's name.")]), ("aws_get_k8s_version", "EKS's supported Kubernetes versions", "eks", "describe_cluster_versions", "{}", []), ("aws_get_service", "one App Runner service", "apprunner", "describe_service", '{"ServiceArn": arguments.get("arn")}', [aws_id("arn", "The service's ARN.")]), ("aws_get_function", "one Lambda function's configuration", "lambda", "get_function_configuration", '{"FunctionName": arguments.get("name")}', [aws_id("name", "The function's name.")]), ("aws_get_sql_instance", "one RDS instance", "rds", "describe_db_instances", '{"DBInstanceIdentifier": arguments.get("name")}', [aws_id("name", "The instance's identifier.")]), ("aws_get_topic", "one SNS topic", "sns", "get_topic_attributes", '{"TopicArn": arguments.get("arn")}', [aws_id("arn", "The topic's ARN.")]), ("aws_get_subscription", "one SNS subscription", "sns", "get_subscription_attributes", '{"SubscriptionArn": arguments.get("arn")}', [aws_id("arn", "The subscription's ARN.")]), ("aws_get_role", "one IAM role", "iam", "get_role", '{"RoleName": arguments.get("name")}', [aws_id("name", "The role's name.")]), ("aws_get_deny_policy", "one service control policy", "organizations", "describe_policy", '{"PolicyId": arguments.get("policy_id")}', [aws_id("policy_id", "The policy id.")]), ("aws_get_alert_policy", "named CloudWatch alarms", "cloudwatch", "describe_alarms", '{"AlarmNames": [arguments.get("name")]}', [aws_id("name", "The alarm's name.")]), ("aws_get_connectivity_test", "one Reachability Analyzer path", "ec2", "describe_network_insights_paths", '{"NetworkInsightsPathIds": [arguments.get("path_id")]}', [aws_id("path_id", "The path id.")]), ("aws_analyze_access", "the account's IAM users, groups, roles and policies", "iam", "get_account_authorization_details", "{}", []), ]: tools.append(tool(name, f"Read {what}.", f' return await _aws_get("{name}", arguments, "{service}", "{operation}", {request})', [*parameters, *AWS_WHERE])) tools.append(tool("aws_list_timeseries", "Read CloudWatch metric values.", ' return await _aws_metric_data("aws_list_timeseries", arguments)', [param("metric_queries", "CloudWatch MetricDataQueries.", "array"), param("start_time", "ISO 8601 start."), param("end_time", "ISO 8601 end."), *AWS_WHERE])) return { "server_id": "sa-aws-cloud", "name": "Solution Architecture AWS", "description": "AWS documentation and read-only estate tools for the Solution Architecture agent, through " "the customer's read-only role.", "version": "0.1.0", "port": 8117, "verify_tool": "aws_check_connection", "shared_code": [f"{SHARED}/tool_support.py", f"{SHARED}/aws_support.py", f"{SHARED}/knowledge_support.py", "_support/docs_log.py", "_support/docs_support.py", "_support/aws_tools.py"], "extra_requirements": ["boto3==1.43.122"], "connection_fields": [ {"name": "access_key_id", "title": "Access key id", "description": "The broker identity that assumes the role.", "required": True, "secret": True}, {"name": "secret_access_key", "title": "Secret access key", "description": "Its secret key.", "required": True, "secret": True}, {"name": "role_arn", "title": "Role ARN", "description": "The read-only role.", "required": True, "secret": False}, {"name": "external_id", "title": "External id", "description": "The role's external id.", "required": False, "secret": True}, {"name": "regions", "title": "Regions", "description": "Comma-separated; the first is the default.", "required": True, "secret": False}, {"name": "account_ids", "title": "Account ids", "description": "Optional member accounts.", "required": False, "secret": False}, {"name": "member_role_name", "title": "Member role name", "description": "The role's name in member accounts.", "required": False, "secret": False}, {"name": "docs_access_key_id", "title": "Documentation access key id", "description": "Identity for the AWS documentation server. Defaults to the broker identity.", "required": False, "secret": True}, {"name": "docs_secret_access_key", "title": "Documentation secret key", "description": "Its secret key.", "required": False, "secret": True}, ], "tools": tools, } def main() -> None: for definition in (gcp(), azure(), aws()): path = HERE / f"{definition['server_id']}.server.yaml" header = "# Generated by build_definitions.py; don't edit by hand.\n# Credentials arrive per call from the Vault Service. Store them per project.\n\n" path.write_text(header + yaml.safe_dump(definition, sort_keys=False, width=120)) print(path.name, len(definition["tools"]), "tools") if __name__ == "__main__": main()