# Solution Architecture Google Cloud Google Cloud documentation and read-only estate tools for the Solution Architecture agent, through Google's hosted MCP servers. **Version:** 0.1.0 **Server ID:** sa-gcp-cloud **Port:** 8115 --- ## 🚀 Quick Start ### As a container (recommended) The Dockerfile builds the server's image. Run it on the same network as the MCP Gateway, so the Gateway can reach it by its container name: ```bash cp .env.example .env # then set MCP_REGISTRATION_API_KEY podman build -t . podman run -d --name --env-file .env --network ``` Register it with the MCP Gateway at `http://:8115`. ### Local Development ```bash # Install dependencies pip install -r requirements.txt # Set environment variables cp .env.example .env # Edit .env with your configuration # Run the server python server.py ``` --- ## 📡 API Endpoints | Endpoint | Method | Description | |----------|--------|-------------| | `/health` | GET | Health check (no auth) | | `/.well-known/mcp-auth` | GET | Authentication requirements | | `/messages` | POST | MCP JSON-RPC 2.0 endpoint | --- ## 🔧 Available Tools - **gcp_check_connection**: Test the stored connection: sign in and open the resource manager server. - **gcp_describe_tool**: Read a hosted tool's live description and argument schema, before calling it. - **gcp_developer_knowledge_search_documents**: Google's search_documents on its developer_knowledge MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_developer_knowledge_get_documents**: Google's get_documents on its developer_knowledge MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_developer_knowledge_answer_query**: Google's answer_query on its developer_knowledge MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_resource_manager_search_projects**: Google's search_projects on its resource_manager MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_asset_inventory_list_assets**: Google's list_assets on its asset_inventory MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_asset_inventory_analyze_iam_policy**: Google's analyze_iam_policy on its asset_inventory MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_list_instances**: Google's list_instances on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_get_instance_basic_info**: Google's get_instance_basic_info on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_list_instance_attached_disks**: Google's list_instance_attached_disks on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_list_instance_group_managers**: Google's list_instance_group_managers on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_get_instance_group_manager_basic_info**: Google's get_instance_group_manager_basic_info on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_list_instance_templates**: Google's list_instance_templates on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_get_instance_template_properties**: Google's get_instance_template_properties on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_list_disks**: Google's list_disks on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_get_disk_basic_info**: Google's get_disk_basic_info on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_list_reservations**: Google's list_reservations on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_compute_list_commitments**: Google's list_commitments on its compute MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_gke_list_clusters**: Google's list_clusters on its gke MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_gke_get_cluster**: Google's get_cluster on its gke MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_gke_list_node_pools**: Google's list_node_pools on its gke MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_gke_get_node_pool**: Google's get_node_pool on its gke MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_gke_get_k8s_version**: Google's get_k8s_version on its gke MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_cloud_run_list_services**: Google's list_services on its cloud_run MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_cloud_run_get_service**: Google's get_service on its cloud_run MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_cloud_sql_list_instances**: Google's list_instances on its cloud_sql MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_cloud_sql_get_instance**: Google's get_instance on its cloud_sql MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_storage_list_buckets**: Google's list_buckets on its storage MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_pubsub_list_topics**: Google's list_topics on its pubsub MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_pubsub_get_topic**: Google's get_topic on its pubsub MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_pubsub_list_subscriptions**: Google's list_subscriptions on its pubsub MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_pubsub_get_subscription**: Google's get_subscription on its pubsub MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_iam_list_roles**: Google's list_roles on its iam MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_iam_get_role**: Google's get_role on its iam MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_iam_list_deny_policies**: Google's list_deny_policies on its iam MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_iam_get_deny_policy**: Google's get_deny_policy on its iam MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_monitoring_list_alert_policies**: Google's list_alert_policies on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_monitoring_get_alert_policy**: Google's get_alert_policy on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_monitoring_list_dashboards**: Google's list_dashboards on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_monitoring_list_metric_descriptors**: Google's list_metric_descriptors on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_monitoring_list_timeseries**: Google's list_timeseries on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_network_intelligence_list_connectivity_tests**: Google's list_connectivity_tests on its network_intelligence MCP server, read-only. Call gcp_describe_tool for its arguments. - **gcp_network_intelligence_get_connectivity_test**: Google's get_connectivity_test on its network_intelligence MCP server, read-only. Call gcp_describe_tool for its arguments. --- ## 🔐 Authentication This server uses Bearer token authentication for MCP protocol messages. ```bash # Test with authentication curl -X POST http://localhost:8115/messages \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MCP_REGISTRATION_API_KEY" \ -d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {}}' ``` --- ## 📋 MCP Gateway Registration To register this server with the MCP Gateway: 1. Start the server (see Quick Start) where the MCP Gateway can reach it 2. In the MCP Gateway Hub, go to **MCP Servers** → **Add MCP Server** 3. Enter the server details: - **URL**: Use the **container name** as the hostname (e.g., `http://weather-mcp-server:8115`) - **API Key**: The `MCP_REGISTRATION_API_KEY` from your `.env` file 4. Click the connection test icon to verify connectivity 5. Enable the server > **Note:** The URL is the one the MCP Gateway uses, so for a container on the Gateway's network use its container name, not `localhost`. --- ## 🔑 Credentials per tenant This server does not hold credentials for its upstream. The MCP Gateway reads the tenant's credential from the Vault Service and sends it with each call, in `params._meta["com.kyndryl.mcp/connection"]`. The server advertises what it needs when the gateway calls `initialize`: | Field | Required | Secret | |---|---|---| | `service_account_json` | yes | yes | | `scope_root` | yes | no | | `quota_project` | no | no | | `docs_api_key` | no | yes | - In your tool code, read the connection with `get_connection()`, and reuse an upstream client with `get_upstream_client("", build)`, which keeps one per kind and distinct connection. - `REQUIRE_VAULT_CONNECTION` (default `true`): a call that arrives without a connection is refused, instead of using this server's own environment. Set it to `false` only for local runs. - `verify_connection` is the tool the gateway calls to test a stored credential. It reports failure until you implement the check against the upstream. --- ## ✅ Check it before you push `tests/test_conformance.py` checks the running server against what the MCP Gateway expects: it refuses callers without its key, answers JSON-RPC correctly, and, if it declares credential fields, takes the account from each request, refuses a call that carries none, names a missing field, and never repeats a credential in a reply. It needs only `pytest` and `httpx` and imports nothing from the server. ```bash pip install pytest httpx # with the server running (see Quick Start) and its key from .env MCP_SERVER_URL=http://localhost:8115 MCP_REGISTRATION_API_KEY= pytest tests/ -v ``` A check that fails says what to fix. Run it again after you implement your tools, since a tool that reads an environment variable for its credential, or repeats one in an error, fails it. Checks that do not apply (a server with no credential fields) are skipped, not passed. To run it with `REQUIRE_VAULT_CONNECTION=false` on your own machine, set `CONFORMANCE_EXPECT_FAIL_CLOSED=false`. --- ## 🚢 Deploying through the tools repository To have CI build and deploy this server, put this folder in the root of the `modernization-tools-mcp-servers` repository as `solution-architecture-google-cloud/`, then add it to `mcp_servers_to_deploy.yaml` in that repository with the instances it should run on: ```yaml - name: "solution-architecture-google-cloud" instances: - az_dev ``` The pipeline reads `kubernetes/configmap.yaml` for the server's name and port (`MCP_SERVER_NAME`, `SERVER_PORT`), generates the registration key and sets it in the pod, and registers the server with the MCP Gateway. --- ## 📝 Logging Every line the server writes to stdout is one JSON object (`timestamp`, `level`, `event`, `logger`, `server_id`, and for a request `request_id`, `method`, `tool`), including uvicorn's and your tools' own. Each request ends with one `mcp_request_completed` line carrying `outcome`, `duration_ms` and `error_code`. - `LOG_LEVEL` sets the level (default `INFO`). - `LOG_FORMAT=console` prints readable lines instead, for local work. - In your tool code use the module's `logger`: `logger.info("fetched_issue", key=issue_key)`. - Do not log credentials, tokens or Authorization headers. --- ## 🛠️ Development ### Implementing Tools Open `server.py` and find the tool implementation functions. Each tool has a placeholder that needs to be implemented: ```python async def your_tool_name(arguments: Dict[str, Any]) -> Dict[str, Any]: # TODO: Implement this tool raise NotImplementedError("Tool 'your_tool_name' needs implementation") ``` ### Testing ```bash # Health check curl http://localhost:8115/health # List tools curl -X POST http://localhost:8115/messages \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MCP_REGISTRATION_API_KEY" \ -d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {}}' ``` --- ## 📄 License Generated by Agent Builder Platform - Kyndryl (template 1.1.0)