Files
cp1-agents/outcome-pattern/solution_architecture/mcp-servers/sa-aws-cloud/README.md
Jonathan Boniface bc84ee4df6
Some checks failed
check agents / check (push) Failing after 13s
Solution architecture outcome pattern: agent and its MCP servers
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>
2026-11-05 22:13:25 +00:00

237 lines
8.8 KiB
Markdown

# Solution Architecture AWS
AWS documentation and read-only estate tools for the Solution Architecture agent, through the customer's read-only role.
**Version:** 0.1.0
**Server ID:** sa-aws-cloud
**Port:** 8117
---
## 🚀 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>:8117`.
### 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
- **aws_check_connection**: Test the stored connection: assume the role and read its identity. Returns no customer data.
- **aws_search_documents**: Search AWS documentation in free text. Queries are sent as written and logged.
- **aws_get_documents**: Read one AWS documentation page by URL.
- **aws_search_projects**: List the organisation's accounts.
- **aws_list_assets**: List tagged resources.
- **aws_list_instances**: List EC2 instances.
- **aws_list_instance_group_managers**: List Auto Scaling groups.
- **aws_list_instance_templates**: List launch templates.
- **aws_list_disks**: List EBS volumes.
- **aws_list_reservations**: List capacity reservations.
- **aws_list_commitments**: List Savings Plans.
- **aws_list_clusters**: List EKS clusters.
- **aws_list_services**: List App Runner services.
- **aws_list_functions**: List Lambda functions.
- **aws_list_sql_instances**: List RDS instances.
- **aws_list_buckets**: List S3 buckets.
- **aws_list_topics**: List SNS topics.
- **aws_list_subscriptions**: List SNS subscriptions.
- **aws_list_roles**: List IAM roles.
- **aws_list_deny_policies**: List service control policies.
- **aws_list_alert_policies**: List CloudWatch metric alarms.
- **aws_list_dashboards**: List CloudWatch dashboards.
- **aws_list_metric_descriptors**: List CloudWatch metrics.
- **aws_list_connectivity_tests**: List Reachability Analyzer paths.
- **aws_list_node_pools**: List one EKS cluster's node groups.
- **aws_list_instance_attached_disks**: List the EBS volumes attached to one instance.
- **aws_get_instance_basic_info**: Read one EC2 instance.
- **aws_get_instance_group_manager_basic_info**: Read one Auto Scaling group.
- **aws_get_instance_template_properties**: Read a launch template's versions.
- **aws_get_disk_basic_info**: Read one EBS volume.
- **aws_get_cluster**: Read one EKS cluster.
- **aws_get_node_pool**: Read one EKS node group.
- **aws_get_k8s_version**: Read EKS's supported Kubernetes versions.
- **aws_get_service**: Read one App Runner service.
- **aws_get_function**: Read one Lambda function's configuration.
- **aws_get_sql_instance**: Read one RDS instance.
- **aws_get_topic**: Read one SNS topic.
- **aws_get_subscription**: Read one SNS subscription.
- **aws_get_role**: Read one IAM role.
- **aws_get_deny_policy**: Read one service control policy.
- **aws_get_alert_policy**: Read named CloudWatch alarms.
- **aws_get_connectivity_test**: Read one Reachability Analyzer path.
- **aws_analyze_access**: Read the account's IAM users, groups, roles and policies.
- **aws_list_timeseries**: Read CloudWatch metric values.
---
## 🔐 Authentication
This server uses Bearer token authentication for MCP protocol messages.
```bash
# Test with authentication
curl -X POST http://localhost:8117/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:8117`)
- **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 |
|---|---|---|
| `access_key_id` | yes | yes |
| `secret_access_key` | yes | yes |
| `role_arn` | yes | no |
| `external_id` | no | yes |
| `regions` | yes | no |
| `account_ids` | no | no |
| `member_role_name` | no | no |
| `docs_access_key_id` | no | yes |
| `docs_secret_access_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:8117 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-aws/`, then add it to
`mcp_servers_to_deploy.yaml` in that repository with the instances it should
run on:
```yaml
- name: "solution-architecture-aws"
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:8117/health
# List tools
curl -X POST http://localhost:8117/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)