Some checks failed
check agents / check (push) Failing after 13s
The cp1-solution-architecture-agent and the sa-aws/azure/gcp-cloud MCP servers, a separate stream from the individual and sub-agent patterns. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
232 lines
12 KiB
Markdown
232 lines
12 KiB
Markdown
# 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 <image-name> .
|
|
podman run -d --name <container-name> --env-file .env --network <gateway-network> <image-name>
|
|
```
|
|
|
|
Register it with the MCP Gateway at `http://<container-name>: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("<client kind>", 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=<the 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)
|