Add hyperscaler discovery MCP servers and Well-Architected guidance
Some checks failed
check agents / check (push) Failing after 12s
Some checks failed
check agents / check (push) Failing after 12s
azure-discovery, aws-discovery and gcp-discovery collect read-only metadata on servers, workloads, Kubernetes clusters, networks, data stores, policies and provider recommendations. Credentials arrive per call from the vault. Replies are paged, scrubbed of secrets and anonymised, and throttled calls back off. cloud-knowledge searches each provider's Well-Architected guidance from fixed lists only, so no customer detail can leave the platform. Adds shared skills, the render and test tooling, a public Python Dockerfile until the hardened base image is reachable, the customer access guide, the implementation plan and the Vault Service platform issue. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
39
mcp-servers/README.md
Normal file
39
mcp-servers/README.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# MCP servers
|
||||
|
||||
| Server | Port | What it does | Credential |
|
||||
|---|---|---|---|
|
||||
| [`azure-discovery`](azure-discovery/) | 8111 | Read-only discovery of an Azure estate | The customer's, per project |
|
||||
| [`aws-discovery`](aws-discovery/) | 8112 | Read-only discovery of an AWS estate | The customer's, per project |
|
||||
| [`gcp-discovery`](gcp-discovery/) | 8113 | Read-only discovery of a Google Cloud estate | The customer's, per project |
|
||||
| [`cloud-knowledge`](cloud-knowledge/) | 8114 | Well-Architected guidance from each hyperscaler | Kyndryl's, tenant-wide |
|
||||
| [`alz-discovery-sample`](alz-discovery-sample/) | 8110 | The Meridian sample estate, for evals | None |
|
||||
|
||||
Customers grant access as described in [docs/customer-cloud-access.md](../docs/customer-cloud-access.md).
|
||||
|
||||
## Working on a server
|
||||
|
||||
A server's folder is rendered: **don't edit `server.py` by hand.** The sources are:
|
||||
|
||||
| Path | What it holds |
|
||||
|---|---|
|
||||
| `<server>.server.yaml` | The definition: tools, connection fields, added packages |
|
||||
| `_common/tool_support.py` | Redaction, anonymisation, paging and evidence, inlined into every server |
|
||||
| `_common/<provider>_support.py` | Each provider's code |
|
||||
| `_common/test_contract.py` | The rules every server must pass |
|
||||
| `<server>/tests/test_*.py` | That server's own tests |
|
||||
|
||||
After changing a source, render and test:
|
||||
|
||||
```sh
|
||||
python3 scripts/render_mcp_server.py mcp-servers/<server>.server.yaml --out mcp-servers/<server> \
|
||||
--platform ~/platform-engineering/kyndryl-agent-builder/modernization-platform
|
||||
python3 scripts/test_mcp_servers.py <server>
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **Store a discovery server's connection per project, never tenant-wide.** The gateway uses a tenant-wide credential for every project without its own, so one customer's access would serve another's engagement.
|
||||
- **Store `cloud-knowledge`'s connection tenant-wide.** It holds only Kyndryl's access.
|
||||
- **Read-only.** Don't add a tool that creates, changes or deletes anything.
|
||||
- **Every reply goes through `_scrub`,** which removes secrets and anonymises people.
|
||||
- **Knowledge queries come only from the fixed lists** in `_common/knowledge_support.py`. Never add a free-text field.
|
||||
19
mcp-servers/_common/Dockerfile.python
Normal file
19
mcp-servers/_common/Dockerfile.python
Normal file
@@ -0,0 +1,19 @@
|
||||
# Builds any server in this folder on the public python image, for when the template's base image isn't reachable:
|
||||
#
|
||||
# podman build -f mcp-servers/_common/Dockerfile.python -t <server>:<version> mcp-servers/<server>
|
||||
#
|
||||
# The rendered Dockerfile builds on the platform's hardened base, and this doesn't: it's a larger image, with pip
|
||||
# and a full Debian userland. Replace it with the rendered Dockerfile once the base image is available.
|
||||
FROM docker.io/library/python:3.13.16
|
||||
|
||||
WORKDIR /app
|
||||
COPY requirements.txt constraints.txt ./
|
||||
RUN pip install --no-cache-dir -r requirements.txt -c constraints.txt \
|
||||
&& useradd --uid 1000 --no-create-home --shell /usr/sbin/nologin mcp
|
||||
COPY server.py mcp_connection.py ./
|
||||
|
||||
ENV LOG_LEVEL=INFO
|
||||
ENV LOG_FORMAT=json
|
||||
|
||||
USER 1000
|
||||
CMD ["python", "server.py"]
|
||||
159
mcp-servers/_common/aws_support.py
Normal file
159
mcp-servers/_common/aws_support.py
Normal file
@@ -0,0 +1,159 @@
|
||||
# aws-discovery: every read assumes the customer's read-only role, inside the accounts and regions of the connection.
|
||||
import asyncio
|
||||
import boto3
|
||||
from botocore.config import Config as BotoConfig
|
||||
|
||||
AWS_SESSIONS = {}
|
||||
# kind -> (service, operation, result key, token parameter, token in the reply, fixed arguments)
|
||||
AWS_SERVERS = {
|
||||
"instances": ("ec2", "describe_instances", "Reservations", "NextToken", "NextToken", {}),
|
||||
"auto_scaling_groups": ("autoscaling", "describe_auto_scaling_groups", "AutoScalingGroups", "NextToken", "NextToken", {}),
|
||||
"volumes": ("ec2", "describe_volumes", "Volumes", "NextToken", "NextToken", {}),
|
||||
}
|
||||
AWS_WORKLOADS = {
|
||||
"lambda_functions": ("lambda", "list_functions", "Functions", "Marker", "NextMarker", {}),
|
||||
"ecs_clusters": ("ecs", "list_clusters", "clusterArns", "nextToken", "nextToken", {}),
|
||||
"app_runner_services": ("apprunner", "list_services", "ServiceSummaryList", "NextToken", "NextToken", {}),
|
||||
"elastic_beanstalk_environments": ("elasticbeanstalk", "describe_environments", "Environments", "NextToken", "NextToken", {}),
|
||||
}
|
||||
AWS_NETWORK = {
|
||||
"vpcs": ("ec2", "describe_vpcs", "Vpcs", "NextToken", "NextToken", {}),
|
||||
"subnets": ("ec2", "describe_subnets", "Subnets", "NextToken", "NextToken", {}),
|
||||
"route_tables": ("ec2", "describe_route_tables", "RouteTables", "NextToken", "NextToken", {}),
|
||||
"security_groups": ("ec2", "describe_security_groups", "SecurityGroups", "NextToken", "NextToken", {}),
|
||||
"nat_gateways": ("ec2", "describe_nat_gateways", "NatGateways", "NextToken", "NextToken", {}),
|
||||
"internet_gateways": ("ec2", "describe_internet_gateways", "InternetGateways", "NextToken", "NextToken", {}),
|
||||
"transit_gateways": ("ec2", "describe_transit_gateways", "TransitGateways", "NextToken", "NextToken", {}),
|
||||
"vpc_peering": ("ec2", "describe_vpc_peering_connections", "VpcPeeringConnections", "NextToken", "NextToken", {}),
|
||||
"vpc_endpoints": ("ec2", "describe_vpc_endpoints", "VpcEndpoints", "NextToken", "NextToken", {}),
|
||||
"load_balancers": ("elbv2", "describe_load_balancers", "LoadBalancers", "Marker", "NextMarker", {}),
|
||||
}
|
||||
AWS_DATA = {
|
||||
"rds_instances": ("rds", "describe_db_instances", "DBInstances", "Marker", "Marker", {}),
|
||||
"dynamodb_tables": ("dynamodb", "list_tables", "TableNames", "ExclusiveStartTableName", "LastEvaluatedTableName", {}),
|
||||
"s3_buckets": ("s3", "list_buckets", "Buckets", "ContinuationToken", "ContinuationToken", {}),
|
||||
}
|
||||
AWS_ORG_POLICY_TYPES = {"service_control_policies": "SERVICE_CONTROL_POLICY", "resource_control_policies": "RESOURCE_CONTROL_POLICY",
|
||||
"tag_policies": "TAG_POLICY", "backup_policies": "BACKUP_POLICY"}
|
||||
AWS_PILLARS = {"cost_optimizing": "cost", "security": "security", "fault_tolerance": "reliability",
|
||||
"performance": "performance", "operational_excellence": "operations", "service_limits": "reliability"}
|
||||
|
||||
|
||||
def _aws_csv(connection: Dict[str, Any], field: str) -> List[str]:
|
||||
return [v.strip() for v in str(connection.get(field) or "").split(",") if v.strip()]
|
||||
|
||||
|
||||
def _aws_session(connection: Dict[str, Any], account_id: Optional[str]):
|
||||
"""A session on the customer's read-only role, or on the member account's when one is named."""
|
||||
key = hashlib.sha256(json.dumps([connection, account_id], sort_keys=True).encode()).hexdigest()
|
||||
cached = AWS_SESSIONS.get(key)
|
||||
now = time.time()
|
||||
if cached and cached[1] > now + 60:
|
||||
return cached[0]
|
||||
|
||||
def assume(session, role_arn, external_id=None):
|
||||
region = _aws_csv(connection, "regions")[0]
|
||||
request = {"RoleArn": role_arn, "RoleSessionName": "kab-discovery", "DurationSeconds": 3600}
|
||||
if external_id:
|
||||
request["ExternalId"] = external_id
|
||||
found = session.client("sts", region_name=region).assume_role(**request)["Credentials"]
|
||||
return boto3.Session(aws_access_key_id=found["AccessKeyId"], aws_secret_access_key=found["SecretAccessKey"],
|
||||
aws_session_token=found["SessionToken"])
|
||||
|
||||
base = boto3.Session(aws_access_key_id=connection["access_key_id"], aws_secret_access_key=connection["secret_access_key"])
|
||||
session = assume(base, connection["role_arn"], connection.get("external_id"))
|
||||
if account_id:
|
||||
partition = str(connection["role_arn"]).split(":")[1]
|
||||
session = assume(session, f"arn:{partition}:iam::{account_id}:role/{connection['member_role_name']}")
|
||||
AWS_SESSIONS[key] = (session, now + 3000)
|
||||
return session
|
||||
|
||||
|
||||
def _aws_target(arguments: Dict[str, Any]):
|
||||
"""(account, region) or a refusal. Nothing outside the connection's accounts and regions is ever reached."""
|
||||
connection = get_connection()
|
||||
regions = _aws_csv(connection, "regions")
|
||||
region = arguments.get("region") or regions[0]
|
||||
if region not in regions:
|
||||
return None, None, _refuse("outside_scope", "region isn't in this connection's regions")
|
||||
account = arguments.get("account_id")
|
||||
if account and (account not in _aws_csv(connection, "account_ids") or not connection.get("member_role_name")):
|
||||
return None, None, _refuse("outside_scope", "account_id isn't in this connection's accounts")
|
||||
return account, region, None
|
||||
|
||||
|
||||
async def _aws_call(arguments: Dict[str, Any], service: str, operation: str, region: Optional[str] = None, **request):
|
||||
connection = get_connection()
|
||||
account = arguments.get("account_id")
|
||||
where = region or arguments.get("region") or _aws_csv(connection, "regions")[0]
|
||||
|
||||
def run():
|
||||
# Adaptive mode slows the client down when AWS throttles it, on top of retrying.
|
||||
retries = BotoConfig(retries={"max_attempts": 6, "mode": "adaptive"}, read_timeout=60, connect_timeout=10)
|
||||
client = _aws_session(connection, account).client(service, region_name=where, config=retries)
|
||||
return getattr(client, operation)(**request)
|
||||
|
||||
return await asyncio.to_thread(run)
|
||||
|
||||
|
||||
async def _aws_kind(tool: str, arguments: Dict[str, Any], kinds: Dict[str, tuple], default: str) -> Dict[str, Any]:
|
||||
kind = arguments.get("kind") or default
|
||||
if kind not in kinds:
|
||||
return _refuse("unknown_kind", "kind must be one of: " + ", ".join(kinds))
|
||||
account, region, refused = _aws_target(arguments)
|
||||
if refused:
|
||||
return refused
|
||||
service, operation, result_key, token_in, token_out, fixed = kinds[kind]
|
||||
try:
|
||||
upstream, skip = _read_page(arguments)
|
||||
except (ValueError, KeyError, TypeError):
|
||||
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
||||
request = dict(fixed)
|
||||
if upstream:
|
||||
request[token_in] = upstream
|
||||
try:
|
||||
body = await _aws_call(arguments, service, operation, region, **request)
|
||||
except Exception as error:
|
||||
return _upstream_failed("aws", error)
|
||||
extra = {"account_id": account, "region": region, "kind": kind}
|
||||
return _page_result("aws", tool, arguments, body.get(result_key, []), upstream, body.get(token_out), skip, extra)
|
||||
|
||||
|
||||
async def _aws_each(tool: str, arguments: Dict[str, Any], list_kind: tuple, read) -> Dict[str, Any]:
|
||||
"""List one page of things, then read a detail for each. A detail that's absent or refused is reported."""
|
||||
account, region, refused = _aws_target(arguments)
|
||||
if refused:
|
||||
return refused
|
||||
service, operation, result_key, token_in, token_out, fixed = list_kind
|
||||
try:
|
||||
upstream, skip = _read_page(arguments)
|
||||
except (ValueError, KeyError, TypeError):
|
||||
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
||||
request = dict(fixed)
|
||||
if upstream:
|
||||
request[token_in] = upstream
|
||||
try:
|
||||
body = await _aws_call(arguments, service, operation, region, **request)
|
||||
except Exception as error:
|
||||
return _upstream_failed("aws", error)
|
||||
items = []
|
||||
for entry in body.get(result_key, [])[skip:skip + _page_size(arguments)]:
|
||||
try:
|
||||
items.append(await read(entry, region))
|
||||
except Exception as error:
|
||||
items.append({"resource": entry, "unread": type(error).__name__})
|
||||
consumed = skip + len(items)
|
||||
more = consumed < len(body.get(result_key, []))
|
||||
next_upstream = upstream if more else body.get(token_out)
|
||||
result = _page_result("aws", tool, arguments, items, None, None, 0, {"account_id": account, "region": region})
|
||||
if more or next_upstream:
|
||||
result["data"]["next_page_token"] = _write_page(next_upstream, consumed if more else 0)
|
||||
return result
|
||||
|
||||
|
||||
def _aws_document(text: Any) -> Any:
|
||||
"""A policy document, parsed when it arrives as a JSON string, so its principals can be scrubbed."""
|
||||
try:
|
||||
return json.loads(text) if isinstance(text, str) else text
|
||||
except ValueError:
|
||||
return text
|
||||
171
mcp-servers/_common/azure_support.py
Normal file
171
mcp-servers/_common/azure_support.py
Normal file
@@ -0,0 +1,171 @@
|
||||
# azure-discovery: every read goes through Azure Resource Graph, so the scope sent with each query is the boundary.
|
||||
AZURE_CLOUDS = {
|
||||
"public": {"login": "https://login.microsoftonline.com", "arm": "https://management.azure.com"},
|
||||
"usgov": {"login": "https://login.microsoftonline.us", "arm": "https://management.usgovcloudapi.net"},
|
||||
"china": {"login": "https://login.chinacloudapi.cn", "arm": "https://management.chinacloudapi.cn"},
|
||||
}
|
||||
AZURE_GRAPH_VERSION = "2022-10-01"
|
||||
AZURE_LOCKS_VERSION = "2020-05-01"
|
||||
AZURE_TABLES = ("resources", "resourcecontainers", "policyresources", "advisorresources", "networkresources")
|
||||
AZURE_TOKENS = {}
|
||||
AZURE_SERVERS = {
|
||||
"virtual_machines": ["microsoft.compute/virtualmachines"],
|
||||
"scale_sets": ["microsoft.compute/virtualmachinescalesets"],
|
||||
"disks": ["microsoft.compute/disks"],
|
||||
}
|
||||
AZURE_WORKLOADS = {
|
||||
"app_service": ["microsoft.web/sites", "microsoft.web/serverfarms"],
|
||||
"container_apps": ["microsoft.app/containerapps", "microsoft.app/managedenvironments"],
|
||||
"container_instances": ["microsoft.containerinstance/containergroups"],
|
||||
}
|
||||
AZURE_KUBERNETES = {"clusters": ["microsoft.containerservice/managedclusters"]}
|
||||
AZURE_NETWORK = {
|
||||
"virtual_networks": ["microsoft.network/virtualnetworks"],
|
||||
"route_tables": ["microsoft.network/routetables"],
|
||||
"network_security_groups": ["microsoft.network/networksecuritygroups"],
|
||||
"gateways": ["microsoft.network/virtualnetworkgateways", "microsoft.network/expressroutecircuits",
|
||||
"microsoft.network/natgateways", "microsoft.network/azurefirewalls",
|
||||
"microsoft.network/applicationgateways"],
|
||||
"load_balancers": ["microsoft.network/loadbalancers"],
|
||||
"private_endpoints": ["microsoft.network/privateendpoints"],
|
||||
"public_ips": ["microsoft.network/publicipaddresses"],
|
||||
}
|
||||
AZURE_DATA = {
|
||||
"sql": ["microsoft.sql/servers", "microsoft.sql/servers/databases"],
|
||||
"cosmos_db": ["microsoft.documentdb/databaseaccounts"],
|
||||
"storage_accounts": ["microsoft.storage/storageaccounts"],
|
||||
}
|
||||
AZURE_ORG_POLICIES = {
|
||||
"assignments": ["microsoft.authorization/policyassignments"],
|
||||
"definitions": ["microsoft.authorization/policydefinitions"],
|
||||
"initiatives": ["microsoft.authorization/policysetdefinitions"],
|
||||
"exemptions": ["microsoft.authorization/policyexemptions"],
|
||||
"compliance": ["microsoft.policyinsights/policystates"],
|
||||
}
|
||||
AZURE_RESOURCE_POLICIES = {
|
||||
"key_vault_access": ["microsoft.keyvault/vaults"],
|
||||
"storage_network_rules": ["microsoft.storage/storageaccounts"],
|
||||
}
|
||||
AZURE_PILLARS = {"cost": "cost", "security": "security", "highavailability": "reliability",
|
||||
"performance": "performance", "operationalexcellence": "operations"}
|
||||
|
||||
|
||||
def _azure_scope(connection: Dict[str, Any]) -> Dict[str, List[str]]:
|
||||
"""The query scope: the connection's root, and nothing the caller can widen."""
|
||||
kind, _, identifier = str(connection.get("scope_root", "")).strip("/").partition("/")
|
||||
if not identifier or "/" in identifier or kind not in ("managementGroups", "subscriptions"):
|
||||
raise ValueError("scope_root must be managementGroups/<id> or subscriptions/<id>")
|
||||
return {kind: [identifier]}
|
||||
|
||||
|
||||
def _azure_endpoints(connection: Dict[str, Any]) -> Dict[str, str]:
|
||||
return AZURE_CLOUDS.get(str(connection.get("cloud") or "public"), AZURE_CLOUDS["public"])
|
||||
|
||||
|
||||
def _azure_client():
|
||||
return get_upstream_client("azure", lambda c: httpx.AsyncClient(timeout=100))
|
||||
|
||||
|
||||
async def _azure_token(connection: Dict[str, Any]) -> str:
|
||||
"""A token for Resource Graph: the short-lived one stored for a trial, or one signed in with the app registration."""
|
||||
if connection.get("access_token"):
|
||||
return str(connection["access_token"])
|
||||
if not all(connection.get(f) for f in ("tenant_id", "client_id", "client_secret")):
|
||||
raise ValueError("the connection needs access_token, or tenant_id, client_id and client_secret")
|
||||
key = hashlib.sha256(json.dumps(connection, sort_keys=True).encode()).hexdigest()
|
||||
cached = AZURE_TOKENS.get(key)
|
||||
now = time.time()
|
||||
if cached and cached[1] > now + 60:
|
||||
return cached[0]
|
||||
endpoints = _azure_endpoints(connection)
|
||||
response = await _azure_client().post(
|
||||
f"{endpoints['login']}/{connection['tenant_id']}/oauth2/v2.0/token",
|
||||
data={"grant_type": "client_credentials", "client_id": connection["client_id"],
|
||||
"client_secret": connection["client_secret"], "scope": f"{endpoints['arm']}/.default"})
|
||||
response.raise_for_status()
|
||||
body = response.json()
|
||||
AZURE_TOKENS[key] = (body["access_token"], now + int(body.get("expires_in", 3600)))
|
||||
return body["access_token"]
|
||||
|
||||
|
||||
async def _azure_graph(query: str, top: int, skip_token: Optional[str] = None) -> Dict[str, Any]:
|
||||
connection = get_connection()
|
||||
options = {"$top": top, "resultFormat": "objectArray"}
|
||||
if skip_token:
|
||||
options["$skipToken"] = skip_token
|
||||
token = await _azure_token(connection)
|
||||
response = await _with_backoff(lambda: _azure_client().post(
|
||||
f"{_azure_endpoints(connection)['arm']}/providers/Microsoft.ResourceGraph/resources",
|
||||
params={"api-version": AZURE_GRAPH_VERSION}, headers={"Authorization": f"Bearer {token}"},
|
||||
json={"query": query, "options": options, **_azure_scope(connection)}))
|
||||
response.raise_for_status()
|
||||
return response.json()
|
||||
|
||||
|
||||
async def _azure_page(tool: str, arguments: Dict[str, Any], query: str, finish=None) -> Dict[str, Any]:
|
||||
try:
|
||||
upstream, skip = _read_page(arguments)
|
||||
except (ValueError, KeyError, TypeError):
|
||||
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
||||
try:
|
||||
body = await _azure_graph(query, _page_size(arguments), upstream)
|
||||
except Exception as error:
|
||||
return _upstream_failed("azure", error)
|
||||
items = [finish(i) for i in body.get("data", [])] if finish else body.get("data", [])
|
||||
return _page_result("azure", tool, arguments, items, upstream, body.get("$skipToken"), skip)
|
||||
|
||||
|
||||
def _azure_type_query(table: str, types: List[str]) -> str:
|
||||
listed = ", ".join(f"'{t}'" for t in types)
|
||||
return f"{table} | where type in~ ({listed}) | order by id asc"
|
||||
|
||||
|
||||
async def _azure_kind(tool: str, arguments: Dict[str, Any], kinds: Dict[str, List[str]], table: str = "Resources",
|
||||
default: Optional[str] = None, finish=None) -> Dict[str, Any]:
|
||||
kind = arguments.get("kind") or default or next(iter(kinds))
|
||||
if kind not in kinds:
|
||||
return _refuse("unknown_kind", "kind must be one of: " + ", ".join(kinds))
|
||||
return await _azure_page(tool, arguments, _azure_type_query(table, kinds[kind]), finish)
|
||||
|
||||
|
||||
def _azure_recommendation(item: Dict[str, Any]) -> Dict[str, Any]:
|
||||
category = str(item.get("properties", {}).get("category", ""))
|
||||
return {**item, "pillar": AZURE_PILLARS.get(category.lower(), "other"), "provider_category": category}
|
||||
|
||||
|
||||
async def _azure_lock_subscription(arguments: Dict[str, Any]):
|
||||
"""The subscription to read locks from, or None. Resource Graph, under the connection's scope, sets the boundary."""
|
||||
kind, identifiers = next(iter(_azure_scope(get_connection()).items()))
|
||||
wanted = arguments.get("subscription_id")
|
||||
if kind == "subscriptions":
|
||||
return identifiers[0] if wanted in (None, identifiers[0]) else None
|
||||
if not wanted or not re.fullmatch(r"[A-Za-z0-9\-]+", str(wanted)):
|
||||
return None
|
||||
query = f"ResourceContainers | where type =~ 'microsoft.resources/subscriptions' and subscriptionId =~ '{wanted}'"
|
||||
return wanted if (await _azure_graph(query, 1)).get("data") else None
|
||||
|
||||
|
||||
async def _azure_locks(tool: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""Resource locks, from ARM: Resource Graph doesn't hold them, and answers 0 whether or not any exist."""
|
||||
try:
|
||||
upstream, skip = _read_page(arguments)
|
||||
except (ValueError, KeyError, TypeError):
|
||||
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
||||
connection = get_connection()
|
||||
try:
|
||||
subscription = await _azure_lock_subscription(arguments)
|
||||
if not subscription:
|
||||
return _refuse("outside_scope", "subscription_id must name a subscription under this connection's scope")
|
||||
base = f"{_azure_endpoints(connection)['arm']}/subscriptions/{subscription}/providers/Microsoft.Authorization/locks"
|
||||
# A page token carries ARM's next link, and the bearer token goes wherever it points, so it must stay here.
|
||||
url = upstream or f"{base}?api-version={AZURE_LOCKS_VERSION}"
|
||||
if not url.startswith(f"{base}?"):
|
||||
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
||||
token = await _azure_token(connection)
|
||||
response = await _with_backoff(lambda: _azure_client().get(url, headers={"Authorization": f"Bearer {token}"}))
|
||||
response.raise_for_status()
|
||||
body = response.json()
|
||||
except Exception as error:
|
||||
return _upstream_failed("azure", error)
|
||||
return _page_result("azure", tool, arguments, body.get("value", []), upstream, body.get("nextLink"), skip,
|
||||
{"subscription_id": subscription, "kind": "resource_locks"})
|
||||
133
mcp-servers/_common/gcp_support.py
Normal file
133
mcp-servers/_common/gcp_support.py
Normal file
@@ -0,0 +1,133 @@
|
||||
# gcp-discovery: every read goes through Cloud Asset Inventory or another read API, under the connection's scope_root.
|
||||
import asyncio
|
||||
from google.auth.transport.requests import Request as GoogleRequest
|
||||
from google.oauth2 import service_account
|
||||
|
||||
GCP_ASSET_API = "https://cloudasset.googleapis.com/v1"
|
||||
GCP_ORG_POLICY_API = "https://orgpolicy.googleapis.com/v2"
|
||||
GCP_RECOMMENDER_API = "https://recommender.googleapis.com/v1"
|
||||
GCP_READ_ONLY = "https://www.googleapis.com/auth/cloud-platform.read-only"
|
||||
GCP_TOKENS = {}
|
||||
GCP_SERVERS = {
|
||||
"instances": ["compute.googleapis.com/Instance"],
|
||||
"instance_groups": ["compute.googleapis.com/InstanceGroupManager"],
|
||||
"disks": ["compute.googleapis.com/Disk"],
|
||||
}
|
||||
GCP_WORKLOADS = {
|
||||
"cloud_run": ["run.googleapis.com/Service"],
|
||||
"cloud_functions": ["cloudfunctions.googleapis.com/Function"],
|
||||
"app_engine": ["appengine.googleapis.com/Service"],
|
||||
}
|
||||
GCP_KUBERNETES = {"clusters": ["container.googleapis.com/Cluster"], "node_pools": ["container.googleapis.com/NodePool"]}
|
||||
GCP_NETWORK = {
|
||||
"networks": ["compute.googleapis.com/Network"],
|
||||
"subnetworks": ["compute.googleapis.com/Subnetwork"],
|
||||
"routes": ["compute.googleapis.com/Route"],
|
||||
"firewall_rules": ["compute.googleapis.com/Firewall", "compute.googleapis.com/FirewallPolicy"],
|
||||
"load_balancers": ["compute.googleapis.com/ForwardingRule", "compute.googleapis.com/BackendService"],
|
||||
"gateways": ["compute.googleapis.com/Router", "compute.googleapis.com/VpnGateway",
|
||||
"compute.googleapis.com/InterconnectAttachment"],
|
||||
}
|
||||
GCP_DATA = {
|
||||
"cloud_sql": ["sqladmin.googleapis.com/Instance"],
|
||||
"firestore": ["firestore.googleapis.com/Database"],
|
||||
"cloud_storage": ["storage.googleapis.com/Bucket"],
|
||||
}
|
||||
GCP_ACCOUNTS = {
|
||||
"projects": ["cloudresourcemanager.googleapis.com/Project"],
|
||||
"folders": ["cloudresourcemanager.googleapis.com/Folder"],
|
||||
}
|
||||
GCP_PERIMETERS = {"vpc_service_controls": ["accesscontextmanager.googleapis.com/ServicePerimeter"]}
|
||||
GCP_RECOMMENDERS = ("google.compute.instance.MachineTypeRecommender", "google.compute.instance.IdleResourceRecommender",
|
||||
"google.compute.disk.IdleResourceRecommender", "google.iam.policy.Recommender")
|
||||
GCP_PILLARS = {"cost": "cost", "security": "security", "performance": "performance", "reliability": "reliability",
|
||||
"manageability": "operations", "sustainability": "sustainability"}
|
||||
|
||||
|
||||
def _gcp_scope() -> str:
|
||||
scope = str(get_connection().get("scope_root", "")).strip("/")
|
||||
kind, _, identifier = scope.partition("/")
|
||||
if kind not in ("organizations", "folders", "projects") or not identifier or "/" in identifier:
|
||||
raise ValueError("scope_root must be organizations/<id>, folders/<id> or projects/<id>")
|
||||
return scope
|
||||
|
||||
|
||||
def _gcp_client():
|
||||
return get_upstream_client("gcp", lambda c: httpx.AsyncClient(timeout=100))
|
||||
|
||||
|
||||
async def _gcp_token() -> str:
|
||||
connection = get_connection()
|
||||
key = hashlib.sha256(json.dumps(connection, sort_keys=True).encode()).hexdigest()
|
||||
cached = GCP_TOKENS.get(key)
|
||||
now = time.time()
|
||||
if cached and cached[1] > now + 60:
|
||||
return cached[0]
|
||||
|
||||
def refresh():
|
||||
info = json.loads(connection["service_account_json"])
|
||||
credentials = service_account.Credentials.from_service_account_info(info, scopes=[GCP_READ_ONLY])
|
||||
credentials.refresh(GoogleRequest())
|
||||
return credentials.token
|
||||
|
||||
token = await asyncio.to_thread(refresh)
|
||||
GCP_TOKENS[key] = (token, now + 3000)
|
||||
return token
|
||||
|
||||
|
||||
async def _gcp_get(url: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
||||
token = await _gcp_token()
|
||||
response = await _with_backoff(
|
||||
lambda: _gcp_client().get(url, params=params, headers={"Authorization": f"Bearer {token}"}))
|
||||
response.raise_for_status()
|
||||
return response.json()
|
||||
|
||||
|
||||
async def _gcp_page(tool: str, arguments: Dict[str, Any], url: str, params: Dict[str, Any], result_key: str,
|
||||
finish=None) -> Dict[str, Any]:
|
||||
try:
|
||||
upstream, skip = _read_page(arguments)
|
||||
except (ValueError, KeyError, TypeError):
|
||||
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
||||
request = {**params, "pageSize": _page_size(arguments)}
|
||||
if upstream:
|
||||
request["pageToken"] = upstream
|
||||
try:
|
||||
body = await _gcp_get(url, request)
|
||||
except Exception as error:
|
||||
return _upstream_failed("gcp", error)
|
||||
items = [finish(i) for i in body.get(result_key, [])] if finish else body.get(result_key, [])
|
||||
return _page_result("gcp", tool, arguments, items, upstream, body.get("nextPageToken"), skip)
|
||||
|
||||
|
||||
async def _gcp_search(tool: str, arguments: Dict[str, Any], asset_types: List[str], query: str = "") -> Dict[str, Any]:
|
||||
try:
|
||||
url = f"{GCP_ASSET_API}/{_gcp_scope()}:searchAllResources"
|
||||
except ValueError as error:
|
||||
return _refuse("invalid_connection", str(error))
|
||||
params = {"assetTypes": asset_types, "readMask": "*"}
|
||||
if query:
|
||||
params["query"] = query
|
||||
return await _gcp_page(tool, arguments, url, params, "results")
|
||||
|
||||
|
||||
async def _gcp_kind(tool: str, arguments: Dict[str, Any], kinds: Dict[str, List[str]], default: str) -> Dict[str, Any]:
|
||||
kind = arguments.get("kind") or default
|
||||
if kind not in kinds:
|
||||
return _refuse("unknown_kind", "kind must be one of: " + ", ".join(kinds))
|
||||
return await _gcp_search(tool, arguments, kinds[kind])
|
||||
|
||||
|
||||
async def _gcp_project_in_scope(project_id: str) -> bool:
|
||||
"""Whether Cloud Asset, queried under the scope, can see this project. The API sets the boundary."""
|
||||
scope = _gcp_scope()
|
||||
if scope == f"projects/{project_id}":
|
||||
return True
|
||||
body = await _gcp_get(f"{GCP_ASSET_API}/{scope}:searchAllResources",
|
||||
{"assetTypes": GCP_ACCOUNTS["projects"], "query": f"name:{project_id}", "pageSize": 5})
|
||||
return any(str(r.get("name", "")).endswith(f"/projects/{project_id}") for r in body.get("results", []))
|
||||
|
||||
|
||||
def _gcp_recommendation(item: Dict[str, Any]) -> Dict[str, Any]:
|
||||
category = str(item.get("primaryImpact", {}).get("category", ""))
|
||||
return {**item, "pillar": GCP_PILLARS.get(category.lower(), "other"), "provider_category": category}
|
||||
108
mcp-servers/_common/knowledge_support.py
Normal file
108
mcp-servers/_common/knowledge_support.py
Normal file
@@ -0,0 +1,108 @@
|
||||
# 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
|
||||
125
mcp-servers/_common/test_contract.py
Normal file
125
mcp-servers/_common/test_contract.py
Normal file
@@ -0,0 +1,125 @@
|
||||
"""The contract every hyperscaler server must meet. Run once per server: SERVER_DIR=<folder> pytest _common/test_contract.py"""
|
||||
import asyncio
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
SERVER_DIR = Path(os.environ["SERVER_DIR"]).resolve()
|
||||
sys.path.insert(0, str(SERVER_DIR))
|
||||
import server # noqa: E402
|
||||
|
||||
CONNECTIONS = {
|
||||
"azure-discovery": {"tenant_id": "t", "client_id": "c", "client_secret": "s", "scope_root": "subscriptions/sub-1"},
|
||||
"aws-discovery": {"access_key_id": "a", "secret_access_key": "b", "role_arn": "arn:aws:iam::111111111111:role/r",
|
||||
"external_id": "e", "regions": "eu-west-2"},
|
||||
"gcp-discovery": {"scope_root": "projects/p1", "service_account_json": "{}"},
|
||||
"cloud-knowledge": {"google_api_key": "k"},
|
||||
}
|
||||
|
||||
|
||||
def test_every_tool_has_a_handler():
|
||||
names = [t["name"] for t in server.TOOLS_REGISTRY]
|
||||
assert "verify_connection" in names
|
||||
assert len(names) == len(set(names))
|
||||
for name in names:
|
||||
assert callable(getattr(server, name))
|
||||
|
||||
|
||||
def test_verify_connection_is_implemented():
|
||||
assert server.VERIFY_TOOL == "verify_connection"
|
||||
assert "does not check it against" not in Path(SERVER_DIR / "server.py").read_text()
|
||||
|
||||
|
||||
def test_connection_is_required_by_default():
|
||||
assert server.config.REQUIRE_VAULT_CONNECTION is True
|
||||
with pytest.raises(ValueError):
|
||||
server.check_connection(None)
|
||||
|
||||
|
||||
def test_no_credential_is_read_from_the_environment():
|
||||
code = Path(SERVER_DIR / "server.py").read_text()
|
||||
for field in CONNECTIONS[SERVER_DIR.name]:
|
||||
assert not re.search(rf"(getenv|environ)[^\n]*{field}", code)
|
||||
|
||||
|
||||
def test_only_read_operations_are_named():
|
||||
"""No create, update, delete or put anywhere in the upstream calls."""
|
||||
if SERVER_DIR.name != "aws-discovery":
|
||||
pytest.skip("only AWS names operations; Azure and Google Cloud are tested on the URLs they reach")
|
||||
code = Path(SERVER_DIR / "server.py").read_text()
|
||||
operations = re.findall(r'_aws_call\([^,]+,\s*"[a-z0-9]+",\s*"([a-z_]+)"', code)
|
||||
operations += re.findall(r'\("[a-z0-9]+",\s*"([a-z_]+)",\s*"[A-Za-z]+",\s*"[A-Za-z]+",\s*"[A-Za-z]+",', code)
|
||||
assert all(op.split("_")[0] in ("list", "describe", "get", "select") for op in operations), operations
|
||||
|
||||
|
||||
@pytest.mark.parametrize("value,expected", [
|
||||
("user:ana@customer.example", "[user]"),
|
||||
("group:admins@customer.example", "[group]"),
|
||||
("domain:customer.example", "[domain]"),
|
||||
("deleted:user:ana@customer.example?uid=1", "[user]"),
|
||||
("serviceAccount:scan@p1.iam.gserviceaccount.com", "serviceAccount:scan@p1.iam.gserviceaccount.com"),
|
||||
])
|
||||
def test_members_are_anonymised(value, expected):
|
||||
assert server._scrub({"members": [value]})["members"] == [expected]
|
||||
|
||||
|
||||
def test_people_never_survive_scrubbing():
|
||||
record = {
|
||||
"tags": {"owner": "Ana Silva", "environment": "prod"},
|
||||
"Tags": [{"Key": "Owner", "Value": "Ana Silva"}, {"Key": "Name", "Value": "web-01"}],
|
||||
"systemData": {"createdBy": "ana@customer.example"},
|
||||
"description": "Contact ana@customer.example for access",
|
||||
"Principal": {"AWS": "arn:aws:iam::111111111111:user/ana"},
|
||||
"session": "arn:aws:sts::111111111111:assumed-role/ops/ana@customer.example",
|
||||
"objectId": "00000000-0000-0000-0000-000000000000",
|
||||
}
|
||||
text = json.dumps(server._scrub(record))
|
||||
assert "ana" not in text.lower().replace("[", "") or "Ana" not in text
|
||||
assert "ana@" not in text and "Ana Silva" not in text and ":user/ana" not in text
|
||||
assert "00000000-0000" not in text
|
||||
assert "web-01" in text and "prod" in text and "assumed-role/ops/[session]" in text
|
||||
|
||||
|
||||
def test_secrets_never_survive_scrubbing():
|
||||
record = {"osProfile": {"customData": "c2VjcmV0", "adminPassword": "x"}, "Environment": {"Variables": {"DB": "y"}},
|
||||
"properties": {"connectionStrings": ["z"], "envVars": [{"name": "A"}]}}
|
||||
text = json.dumps(server._scrub(record))
|
||||
assert "c2VjcmV0" not in text and '"DB"' not in text and '"z"' not in text and '"A"' not in text
|
||||
|
||||
|
||||
def test_page_is_cut_and_resumes_at_the_cut():
|
||||
items = [{"id": i, "pad": "x" * 60000} for i in range(10)]
|
||||
first = server._page_result("t", "tool", {}, items, "up", "next")["data"]
|
||||
assert 0 < first["count"] < 10 and first["next_page_token"]
|
||||
upstream, skip = server._read_page({"page_token": first["next_page_token"]})
|
||||
assert (upstream, skip) == ("up", first["count"])
|
||||
last = server._page_result("t", "tool", {}, items, upstream, "next", skip)["data"]
|
||||
assert last["items"][0]["id"] == first["count"]
|
||||
|
||||
|
||||
def test_failures_do_not_quote_the_upstream():
|
||||
class Boom(Exception):
|
||||
pass
|
||||
|
||||
result = server._upstream_failed("azure", Boom("token=abc user ana@customer.example"))
|
||||
assert "abc" not in json.dumps(result) and "ana@" not in json.dumps(result)
|
||||
|
||||
|
||||
def test_evidence_changes_with_the_content():
|
||||
assert server._evidence_ref("t", {}, [1]) != server._evidence_ref("t", {}, [2])
|
||||
|
||||
|
||||
def test_tools_refuse_a_forged_page_token():
|
||||
if SERVER_DIR.name == "cloud-knowledge":
|
||||
pytest.skip("this server has no paged tools")
|
||||
prefix = SERVER_DIR.name.split("-")[0]
|
||||
token = server.mcp_connection.bind(CONNECTIONS[SERVER_DIR.name])
|
||||
try:
|
||||
result = asyncio.run(getattr(server, f"{prefix}_list_servers")({"page_token": "not-a-token"}))
|
||||
finally:
|
||||
server.mcp_connection.unbind(token)
|
||||
assert result["success"] is False and result["error"]["code"] == "invalid_page_token"
|
||||
180
mcp-servers/_common/tool_support.py
Normal file
180
mcp-servers/_common/tool_support.py
Normal file
@@ -0,0 +1,180 @@
|
||||
# Shared by every hyperscaler server. scripts/render_mcp_server.py inlines this file into a server through the
|
||||
# definition's shared_code, because a rendered image holds only the template's files. The builder accepts plain
|
||||
# functions and literal constants here, nothing that runs at import.
|
||||
import base64
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
|
||||
DEFAULT_PAGE_SIZE = 50
|
||||
MAX_PAGE_SIZE = 200
|
||||
# A reply goes into a model's context, which is the real limit on a hand-off, so a page is cut at this size.
|
||||
MAX_RESPONSE_BYTES = 200000
|
||||
# A throttled call is retried inside the budget, then fails and says so.
|
||||
RETRY_ATTEMPTS = 5
|
||||
RETRY_MAX_WAIT_SECONDS = 20
|
||||
RETRY_BUDGET_SECONDS = 60
|
||||
|
||||
# Values under these keys are never returned, in any casing.
|
||||
SECRET_KEYS = (
|
||||
"userdata", "customdata", "customscript", "protectedsettings", "connectionstring", "connectionstrings",
|
||||
"appsettings", "env", "envvars", "environmentvariables", "variables", "password", "adminpassword", "secret",
|
||||
"secretvalue", "sastoken", "accesskey", "primarykey", "secondarykey", "privatekey", "kubeconfig", "credentials",
|
||||
)
|
||||
# Values under these keys name a person, or may. A principal of unknown type counts as a person.
|
||||
PERSON_KEYS = (
|
||||
"createdby", "lastmodifiedby", "updatedby", "creator", "owner", "owneremail", "contact", "contactemail", "email",
|
||||
"objectid", "principalid", "principalname", "userprincipalname",
|
||||
)
|
||||
PRINCIPAL_KINDS = {"user": "[user]", "group": "[group]", "domain": "[domain]", "principal": "[user]",
|
||||
"principalSet": "[group]", "deleted": "[user]"}
|
||||
NON_PERSON_EMAIL_DOMAINS = ("gserviceaccount.com",)
|
||||
|
||||
|
||||
def _clean_text(text: str) -> str:
|
||||
"""Anonymise people inside a string: emails, AWS IAM users, and session names, which are often emails."""
|
||||
def email(match):
|
||||
return match.group(0) if match.group(0).lower().endswith(NON_PERSON_EMAIL_DOMAINS) else "[email]"
|
||||
|
||||
text = re.sub(r"arn:aws[a-z-]*:iam::\d{12}:user/[^\s\"',]+", "[user]", text)
|
||||
text = re.sub(r"(arn:aws[a-z-]*:sts::\d{12}:assumed-role/[^/\s\"',]+)/[^\s\"',]+", r"\1/[session]", text)
|
||||
# Bounded, and skipped without an @: an unbounded pattern takes minutes on one long string.
|
||||
if "@" not in text:
|
||||
return text
|
||||
return re.sub(r"[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,255}\.[A-Za-z]{2,24}", email, text)
|
||||
|
||||
|
||||
def _anonymise_member(value: str) -> str:
|
||||
"""One IAM member, such as user:a@b.example. Service accounts stay: Discovery shows what can reach what."""
|
||||
kind = value.split(":", 1)[0]
|
||||
if ":" in value and kind == "serviceAccount":
|
||||
return value
|
||||
if ":" in value and kind in PRINCIPAL_KINDS:
|
||||
return PRINCIPAL_KINDS[kind]
|
||||
return _clean_text(value)
|
||||
|
||||
|
||||
def _scrub(value, key: str = ""):
|
||||
"""Drop secrets and anonymise people, however deep. Every tool's reply passes through here."""
|
||||
lowered = key.lower().replace("_", "").replace("-", "")
|
||||
if lowered in SECRET_KEYS:
|
||||
return "[redacted]"
|
||||
if lowered in PERSON_KEYS:
|
||||
return "[user]"
|
||||
if isinstance(value, dict):
|
||||
tag = str(value.get("Key", value.get("key", ""))).lower().replace("_", "").replace("-", "")
|
||||
cleaned = {k: _scrub(v, str(k)) for k, v in value.items()}
|
||||
for name in ("Value", "value"):
|
||||
if name in cleaned and tag in PERSON_KEYS:
|
||||
cleaned[name] = "[user]"
|
||||
elif name in cleaned and tag in SECRET_KEYS:
|
||||
cleaned[name] = "[redacted]"
|
||||
return cleaned
|
||||
if isinstance(value, (list, tuple)):
|
||||
return [_scrub(v, "members" if lowered == "members" else "") for v in value]
|
||||
if isinstance(value, str):
|
||||
return _anonymise_member(value) if lowered == "members" else _clean_text(value)
|
||||
if value is None or isinstance(value, (bool, int, float)):
|
||||
return value
|
||||
return str(value)
|
||||
|
||||
|
||||
def _retry_delay(response, attempt: int) -> float:
|
||||
"""How long the provider asked us to wait: Retry-After, or Resource Graph's hh:mm:ss quota reset."""
|
||||
reset = response.headers.get("x-ms-user-quota-resets-after", "")
|
||||
if reset.count(":") == 2:
|
||||
hours, minutes, seconds = reset.split(":")
|
||||
return int(hours) * 3600 + int(minutes) * 60 + float(seconds)
|
||||
try:
|
||||
return float(response.headers.get("retry-after", ""))
|
||||
except ValueError:
|
||||
return float(2 ** attempt)
|
||||
|
||||
|
||||
async def _with_backoff(send):
|
||||
"""Send, waiting when the provider throttles. The waits stay well inside the 120-second limit on an MCP call."""
|
||||
waited = 0.0
|
||||
response = await send()
|
||||
for attempt in range(RETRY_ATTEMPTS):
|
||||
if response.status_code not in (429, 503):
|
||||
return response
|
||||
delay = min(_retry_delay(response, attempt), RETRY_MAX_WAIT_SECONDS)
|
||||
if waited + delay > RETRY_BUDGET_SECONDS:
|
||||
return response
|
||||
logger.info("upstream_throttled", status=response.status_code, wait_seconds=delay)
|
||||
await asyncio.sleep(delay)
|
||||
waited += delay
|
||||
response = await send()
|
||||
return response
|
||||
|
||||
|
||||
def _page_size(arguments: Dict[str, Any]) -> int:
|
||||
try:
|
||||
size = int(arguments.get("page_size") or DEFAULT_PAGE_SIZE)
|
||||
except (TypeError, ValueError):
|
||||
return DEFAULT_PAGE_SIZE
|
||||
return max(1, min(size, MAX_PAGE_SIZE))
|
||||
|
||||
|
||||
def _read_page(arguments: Dict[str, Any]):
|
||||
"""(upstream token, items of that upstream page already returned)."""
|
||||
token = arguments.get("page_token")
|
||||
if not token:
|
||||
return None, 0
|
||||
state = json.loads(base64.urlsafe_b64decode(str(token).encode()).decode())
|
||||
return state["u"], int(state["s"])
|
||||
|
||||
|
||||
def _write_page(upstream, skip: int) -> str:
|
||||
return base64.urlsafe_b64encode(json.dumps({"u": upstream, "s": skip}).encode()).decode()
|
||||
|
||||
|
||||
def _evidence_ref(tool: str, arguments: Dict[str, Any], payload) -> str:
|
||||
asked = {k: v for k, v in arguments.items() if k != "page_token"}
|
||||
blob = json.dumps([tool, asked, payload], sort_keys=True, default=str)
|
||||
return "sha256:" + hashlib.sha256(blob.encode()).hexdigest()
|
||||
|
||||
|
||||
def _collected_at() -> str:
|
||||
return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
||||
|
||||
|
||||
def _refuse(code: str, message: str) -> Dict[str, Any]:
|
||||
return {"success": False, "error": {"code": code, "message": message}}
|
||||
|
||||
|
||||
def _upstream_failed(provider: str, error: Exception) -> Dict[str, Any]:
|
||||
"""Name the failure and never its text: an upstream error can quote a request or an identity."""
|
||||
status = getattr(getattr(error, "response", None), "status_code", None)
|
||||
code = getattr(error, "response", None)
|
||||
if isinstance(code, dict):
|
||||
status = code.get("Error", {}).get("Code")
|
||||
logger.warning("upstream_call_failed", provider=provider, error_type=type(error).__name__, status=status)
|
||||
detail = f" ({status})" if status else ""
|
||||
return _refuse("upstream_failed", f"{provider} refused or failed the call: {type(error).__name__}{detail}")
|
||||
|
||||
|
||||
def _page_result(provider: str, tool: str, arguments: Dict[str, Any], items: List[Any], used, upstream_next,
|
||||
skip: int = 0, extra: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
||||
"""One page of scrubbed items, cut at MAX_RESPONSE_BYTES; the token resumes exactly where the cut fell."""
|
||||
remaining = [_scrub(item) for item in items[skip:]]
|
||||
kept, size = [], 0
|
||||
for item in remaining:
|
||||
size += len(json.dumps(item, default=str))
|
||||
if kept and size > MAX_RESPONSE_BYTES:
|
||||
break
|
||||
kept.append(item)
|
||||
if len(kept) < len(remaining):
|
||||
next_token = _write_page(used, skip + len(kept))
|
||||
else:
|
||||
next_token = _write_page(upstream_next, 0) if upstream_next else None
|
||||
data = {"provider": provider, "items": kept, "count": len(kept), "next_page_token": next_token,
|
||||
"collected_at": _collected_at(), "evidence_ref": _evidence_ref(tool, arguments, kept)}
|
||||
data.update(extra or {})
|
||||
return {"success": True, "data": data}
|
||||
|
||||
|
||||
def _one_result(provider: str, tool: str, arguments: Dict[str, Any], metadata: Any) -> Dict[str, Any]:
|
||||
clean = _scrub(metadata)
|
||||
return {"success": True, "data": {"provider": provider, "metadata": clean, "collected_at": _collected_at(),
|
||||
"evidence_ref": _evidence_ref(tool, arguments, clean)}}
|
||||
341
mcp-servers/aws-discovery.server.yaml
Normal file
341
mcp-servers/aws-discovery.server.yaml
Normal file
@@ -0,0 +1,341 @@
|
||||
# Read-only discovery of a customer's AWS estate. Render with scripts/render_mcp_server.py.
|
||||
# Credentials arrive per call from the Vault Service. Store them per project, never tenant-wide.
|
||||
|
||||
server_id: aws-discovery
|
||||
name: AWS Discovery
|
||||
description: Read-only discovery of a customer's AWS estate - servers, workloads, Kubernetes clusters, networks,
|
||||
data stores, policies and Trusted Advisor findings.
|
||||
version: 0.1.1
|
||||
port: 8112
|
||||
verify_tool: aws_check_connection
|
||||
shared_code:
|
||||
- _common/tool_support.py
|
||||
- _common/aws_support.py
|
||||
extra_requirements:
|
||||
- boto3==1.43.122
|
||||
connection_fields:
|
||||
- name: access_key_id
|
||||
title: Access key ID
|
||||
description: The broker identity that assumes the read-only role.
|
||||
required: true
|
||||
secret: false
|
||||
- name: secret_access_key
|
||||
title: Secret access key
|
||||
description: The broker identity's secret key.
|
||||
required: true
|
||||
secret: true
|
||||
- name: role_arn
|
||||
title: Role ARN
|
||||
description: The customer's read-only role.
|
||||
required: true
|
||||
secret: false
|
||||
- name: external_id
|
||||
title: External ID
|
||||
description: The external id on the role's trust policy.
|
||||
required: true
|
||||
secret: true
|
||||
- name: regions
|
||||
title: Regions
|
||||
description: Comma-separated regions that may be read. The first is the default.
|
||||
required: true
|
||||
secret: false
|
||||
- name: account_ids
|
||||
title: Account IDs
|
||||
description: Comma-separated member accounts that may be read.
|
||||
required: false
|
||||
secret: false
|
||||
- name: member_role_name
|
||||
title: Member role name
|
||||
description: The read-only role's name in member accounts.
|
||||
required: false
|
||||
secret: false
|
||||
- name: aggregator_name
|
||||
title: Config aggregator
|
||||
description: An AWS Config aggregator for organisation-wide queries.
|
||||
required: false
|
||||
secret: false
|
||||
tools:
|
||||
- name: aws_check_connection
|
||||
display_name: Check connection
|
||||
description: 'Test the stored connection: assume the role and read its identity. Returns no customer data.'
|
||||
parameters: []
|
||||
ai_implementation: |
|
||||
async def aws_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
try:
|
||||
who = await _aws_call(arguments, "sts", "get_caller_identity")
|
||||
except Exception as error:
|
||||
return {"ok": False, "message": _upstream_failed("aws", error)["error"]["message"]}
|
||||
return {"ok": True, "account": who.get("Account"), "message": "Assumed the read-only role."}
|
||||
- name: aws_list_accounts
|
||||
display_name: List accounts
|
||||
description: List the organisation's accounts or organizational units. Needs the management or a delegated administrator
|
||||
account.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: accounts, roots.'
|
||||
required: false
|
||||
- &id001
|
||||
name: page_size
|
||||
type: integer
|
||||
description: Items per page, up to 200. Default 50.
|
||||
required: false
|
||||
- &id002
|
||||
name: page_token
|
||||
type: string
|
||||
description: next_page_token from the previous reply.
|
||||
required: false
|
||||
ai_implementation: |
|
||||
async def aws_list_accounts(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
kinds = {"accounts": ("organizations", "list_accounts", "Accounts", "NextToken", "NextToken", {}), "roots": ("organizations", "list_roots", "Roots", "NextToken", "NextToken", {})}
|
||||
return await _aws_kind("aws_list_accounts", arguments, kinds, "accounts")
|
||||
- name: aws_list_resources
|
||||
display_name: List resources
|
||||
description: List resources of one type that AWS Config has recorded.
|
||||
parameters:
|
||||
- name: resource_type
|
||||
type: string
|
||||
description: A Config type, such as AWS::EC2::Instance.
|
||||
required: true
|
||||
- &id003
|
||||
name: account_id
|
||||
type: string
|
||||
description: 'An account from the connection''s list. Default: the connection''s own.'
|
||||
required: false
|
||||
- &id004
|
||||
name: region
|
||||
type: string
|
||||
description: 'A region from the connection''s list. Default: the first.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def aws_list_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
resource_type = str(arguments.get("resource_type") or "")
|
||||
if not re.fullmatch(r"AWS::[A-Za-z0-9]+::[A-Za-z0-9]+", resource_type):
|
||||
return _refuse("invalid_argument", "resource_type must be a Config type, such as AWS::EC2::Instance")
|
||||
kinds = {"config": ("config", "list_discovered_resources", "resourceIdentifiers", "nextToken", "nextToken", {"resourceType": resource_type})}
|
||||
return await _aws_kind("aws_list_resources", {**arguments, "kind": "config"}, kinds, "config")
|
||||
- name: aws_query_resources
|
||||
display_name: Query resources
|
||||
description: Run a read-only AWS Config advanced query. Uses the organisation aggregator when the connection names
|
||||
one.
|
||||
parameters:
|
||||
- name: query
|
||||
type: string
|
||||
description: A Config SELECT expression.
|
||||
required: true
|
||||
- *id003
|
||||
- *id004
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def aws_query_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
query = str(arguments.get("query") or "").strip()
|
||||
if not query.upper().startswith("SELECT ") or len(query) > 4000:
|
||||
return _refuse("invalid_argument", "query must be a SELECT, up to 4000 characters")
|
||||
aggregator = get_connection().get("aggregator_name")
|
||||
if aggregator:
|
||||
kinds = {"q": ("config", "select_aggregate_resource_config", "Results", "NextToken", "NextToken", {"Expression": query, "ConfigurationAggregatorName": aggregator})}
|
||||
else:
|
||||
kinds = {"q": ("config", "select_resource_config", "Results", "NextToken", "NextToken", {"Expression": query})}
|
||||
result = await _aws_kind("aws_query_resources", {**arguments, "kind": "q"}, kinds, "q")
|
||||
if result.get("success"):
|
||||
result["data"]["items"] = [_scrub(_aws_document(i)) for i in result["data"]["items"]]
|
||||
return result
|
||||
- name: aws_get_resource_metadata
|
||||
display_name: Get resource metadata
|
||||
description: Read-only provider metadata for one resource, from AWS Config.
|
||||
parameters:
|
||||
- name: resource_type
|
||||
type: string
|
||||
description: A Config type.
|
||||
required: true
|
||||
- name: resource_id
|
||||
type: string
|
||||
description: The resource id.
|
||||
required: true
|
||||
- name: scope_entry_id
|
||||
type: string
|
||||
description: The scope entry this answers, echoed in the reply.
|
||||
required: false
|
||||
- *id003
|
||||
- *id004
|
||||
ai_implementation: |
|
||||
async def aws_get_resource_metadata(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
account, region, refused = _aws_target(arguments)
|
||||
if refused:
|
||||
return refused
|
||||
try:
|
||||
body = await _aws_call(arguments, "config", "get_resource_config_history", region, resourceType=arguments.get("resource_type"), resourceId=arguments.get("resource_id"), limit=1)
|
||||
except Exception as error:
|
||||
return _upstream_failed("aws", error)
|
||||
items = body.get("configurationItems", [])
|
||||
if not items:
|
||||
return _refuse("not_found", "AWS Config holds no record of this resource")
|
||||
return _one_result("aws", "aws_get_resource_metadata", arguments, _aws_document(items[0]))
|
||||
- name: aws_list_servers
|
||||
display_name: List servers
|
||||
description: List EC2 instances, Auto Scaling groups or EBS volumes.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: instances, auto_scaling_groups, volumes.'
|
||||
required: false
|
||||
- *id003
|
||||
- *id004
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def aws_list_servers(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _aws_kind("aws_list_servers", arguments, AWS_SERVERS, "instances")
|
||||
- name: aws_list_workloads
|
||||
display_name: List workloads
|
||||
description: List Lambda functions, ECS clusters, App Runner services or Elastic Beanstalk environments. Environment
|
||||
variables are removed.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: lambda_functions, ecs_clusters, app_runner_services, elastic_beanstalk_environments.'
|
||||
required: false
|
||||
- *id003
|
||||
- *id004
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def aws_list_workloads(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _aws_kind("aws_list_workloads", arguments, AWS_WORKLOADS, "lambda_functions")
|
||||
- name: aws_list_kubernetes_clusters
|
||||
display_name: List Kubernetes clusters
|
||||
description: List EKS clusters with version, node groups and networking. Stops at the cloud control plane.
|
||||
parameters:
|
||||
- *id003
|
||||
- *id004
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def aws_list_kubernetes_clusters(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
async def read(name, region):
|
||||
cluster = (await _aws_call(arguments, "eks", "describe_cluster", region, name=name))["cluster"]
|
||||
groups = await _aws_call(arguments, "eks", "list_nodegroups", region, clusterName=name)
|
||||
return {**cluster, "nodegroups": groups.get("nodegroups", [])}
|
||||
return await _aws_each("aws_list_kubernetes_clusters", arguments, ("eks", "list_clusters", "clusters", "nextToken", "nextToken", {}), read)
|
||||
- name: aws_get_network_topology
|
||||
display_name: Get network topology
|
||||
description: List VPCs, subnets, route tables, security groups, NAT or internet gateways, transit gateways, peerings,
|
||||
endpoints or load balancers.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: vpcs, subnets, route_tables, security_groups, nat_gateways, internet_gateways, transit_gateways,
|
||||
vpc_peering, vpc_endpoints, load_balancers.'
|
||||
required: false
|
||||
- *id003
|
||||
- *id004
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def aws_get_network_topology(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _aws_kind("aws_get_network_topology", arguments, AWS_NETWORK, "vpcs")
|
||||
- name: aws_list_data_stores
|
||||
display_name: List data stores
|
||||
description: List RDS instances, DynamoDB tables or S3 buckets. Metadata only, never rows or objects.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: rds_instances, dynamodb_tables, s3_buckets.'
|
||||
required: false
|
||||
- *id003
|
||||
- *id004
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def aws_list_data_stores(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _aws_kind("aws_list_data_stores", arguments, AWS_DATA, "rds_instances")
|
||||
- name: aws_list_organization_policies
|
||||
display_name: List organization policies
|
||||
description: List Organizations policies with their documents, or Config rule compliance.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: service_control_policies, resource_control_policies, tag_policies, backup_policies, config_rule_compliance.'
|
||||
required: false
|
||||
- *id003
|
||||
- *id004
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: "async def aws_list_organization_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:\n \
|
||||
\ kind = arguments.get(\"kind\") or \"service_control_policies\"\n if kind == \"config_rule_compliance\"\
|
||||
:\n kinds = {kind: (\"config\", \"describe_compliance_by_config_rule\", \"ComplianceByConfigRules\",\
|
||||
\ \"NextToken\", \"NextToken\", {})}\n return await _aws_kind(\"aws_list_organization_policies\", arguments,\
|
||||
\ kinds, kind)\n if kind not in AWS_ORG_POLICY_TYPES:\n return _refuse(\"unknown_kind\", \"kind must\
|
||||
\ be one of: \" + \", \".join(AWS_ORG_POLICY_TYPES) + \", config_rule_compliance\")\n \n async def read(entry,\
|
||||
\ region):\n policy = (await _aws_call(arguments, \"organizations\", \"describe_policy\", region, PolicyId=entry[\"\
|
||||
Id\"]))[\"Policy\"]\n targets = await _aws_call(arguments, \"organizations\", \"list_targets_for_policy\"\
|
||||
, region, PolicyId=entry[\"Id\"])\n return {\"policy_id\": entry[\"Id\"], \"name\": entry.get(\"Name\"\
|
||||
), \"type\": entry.get(\"Type\"), \"layer\": \"organisation\", \"aws_managed\": entry.get(\"AwsManaged\"), \"\
|
||||
attached_to\": targets.get(\"Targets\", []), \"document\": _aws_document(policy.get(\"Content\"))}\n return\
|
||||
\ await _aws_each(\"aws_list_organization_policies\", arguments, (\"organizations\", \"list_policies\", \"Policies\"\
|
||||
, \"NextToken\", \"NextToken\", {\"Filter\": AWS_ORG_POLICY_TYPES[kind]}), read)\n"
|
||||
- name: aws_list_resource_policies
|
||||
display_name: List resource policies
|
||||
description: 'List resource-based policies: S3 buckets, KMS keys, Lambda functions, SQS queues, SNS topics, or
|
||||
IAM role trust policies. People are anonymised.'
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: s3_buckets, kms_keys, lambda_functions, sqs_queues, sns_topics, iam_role_trust.'
|
||||
required: false
|
||||
- *id003
|
||||
- *id004
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: "async def aws_list_resource_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:\n kind\
|
||||
\ = arguments.get(\"kind\") or \"s3_buckets\"\n \n def shaped(name, document, resource_type):\n \
|
||||
\ return {\"name\": name, \"type\": resource_type, \"layer\": \"resource\", \"document\": _aws_document(document)}\n\
|
||||
\ \n async def bucket(entry, region):\n body = await _aws_call(arguments, \"s3\", \"get_bucket_policy\"\
|
||||
, region, Bucket=entry[\"Name\"])\n return shaped(entry[\"Name\"], body.get(\"Policy\"), \"s3_bucket\"\
|
||||
)\n \n async def key(entry, region):\n body = await _aws_call(arguments, \"kms\", \"get_key_policy\"\
|
||||
, region, KeyId=entry[\"KeyId\"], PolicyName=\"default\")\n return shaped(entry[\"KeyId\"], body.get(\"\
|
||||
Policy\"), \"kms_key\")\n \n async def function(entry, region):\n body = await _aws_call(arguments,\
|
||||
\ \"lambda\", \"get_policy\", region, FunctionName=entry[\"FunctionName\"])\n return shaped(entry[\"\
|
||||
FunctionName\"], body.get(\"Policy\"), \"lambda_function\")\n \n async def queue(url, region):\n \
|
||||
\ body = await _aws_call(arguments, \"sqs\", \"get_queue_attributes\", region, QueueUrl=url, AttributeNames=[\"\
|
||||
Policy\"])\n return shaped(url, body.get(\"Attributes\", {}).get(\"Policy\"), \"sqs_queue\")\n \n\
|
||||
\ async def topic(entry, region):\n body = await _aws_call(arguments, \"sns\", \"get_topic_attributes\"\
|
||||
, region, TopicArn=entry[\"TopicArn\"])\n return shaped(entry[\"TopicArn\"], body.get(\"Attributes\"\
|
||||
, {}).get(\"Policy\"), \"sns_topic\")\n \n async def role(entry, region):\n return shaped(entry[\"\
|
||||
RoleName\"], entry.get(\"AssumeRolePolicyDocument\"), \"iam_role_trust\")\n \n kinds = {\"s3_buckets\"\
|
||||
: ((\"s3\", \"list_buckets\", \"Buckets\", \"ContinuationToken\", \"ContinuationToken\", {}), bucket),\n \
|
||||
\ \"kms_keys\": ((\"kms\", \"list_keys\", \"Keys\", \"Marker\", \"NextMarker\", {}), key),\n \
|
||||
\ \"lambda_functions\": ((\"lambda\", \"list_functions\", \"Functions\", \"Marker\", \"NextMarker\", {}),\
|
||||
\ function),\n \"sqs_queues\": ((\"sqs\", \"list_queues\", \"QueueUrls\", \"NextToken\", \"NextToken\"\
|
||||
, {}), queue),\n \"sns_topics\": ((\"sns\", \"list_topics\", \"Topics\", \"NextToken\", \"NextToken\"\
|
||||
, {}), topic),\n \"iam_role_trust\": ((\"iam\", \"list_roles\", \"Roles\", \"Marker\", \"Marker\"\
|
||||
, {}), role)}\n if kind not in kinds:\n return _refuse(\"unknown_kind\", \"kind must be one of: \"\
|
||||
\ + \", \".join(kinds))\n return await _aws_each(\"aws_list_resource_policies\", arguments, kinds[kind][0],\
|
||||
\ kinds[kind][1])\n"
|
||||
- name: aws_list_recommendations
|
||||
display_name: List recommendations
|
||||
description: List Trusted Advisor recommendations, each with a common Well-Architected pillar, or the customer's
|
||||
existing Well-Architected Tool reviews.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: trusted_advisor, well_architected_reviews.'
|
||||
required: false
|
||||
- *id003
|
||||
- *id004
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: "async def aws_list_recommendations(arguments: Dict[str, Any]) -> Dict[str, Any]:\n kind\
|
||||
\ = arguments.get(\"kind\") or \"trusted_advisor\"\n if kind == \"well_architected_reviews\":\n async\
|
||||
\ def read(entry, region):\n lenses = await _aws_call(arguments, \"wellarchitected\", \"list_lens_reviews\"\
|
||||
, region, WorkloadId=entry[\"WorkloadId\"])\n return {\"workload\": entry, \"lens_reviews\": lenses.get(\"\
|
||||
LensReviewSummaries\", [])}\n return await _aws_each(\"aws_list_recommendations\", arguments, (\"wellarchitected\"\
|
||||
, \"list_workloads\", \"WorkloadSummaries\", \"NextToken\", \"NextToken\", {}), read)\n if kind != \"trusted_advisor\"\
|
||||
:\n return _refuse(\"unknown_kind\", \"kind must be trusted_advisor or well_architected_reviews\")\n\
|
||||
\ \n async def read(entry, region):\n pillars = entry.get(\"pillars\") or []\n return {**entry,\
|
||||
\ \"pillar\": [AWS_PILLARS.get(p, \"other\") for p in pillars], \"provider_category\": pillars}\n return\
|
||||
\ await _aws_each(\"aws_list_recommendations\", arguments, (\"trustedadvisor\", \"list_recommendations\", \"\
|
||||
recommendationSummaries\", \"nextToken\", \"nextToken\", {}), read)\n"
|
||||
62
mcp-servers/aws-discovery/.env.example
Normal file
62
mcp-servers/aws-discovery/.env.example
Normal file
@@ -0,0 +1,62 @@
|
||||
# ============================================
|
||||
# AWS Discovery - Environment Variables
|
||||
# ============================================
|
||||
# Generated by Agent Builder Platform
|
||||
#
|
||||
# SETUP INSTRUCTIONS:
|
||||
# 1. Copy this file to .env: cp .env.example .env
|
||||
# 2. Generate a secure API key: openssl rand -hex 32
|
||||
# 3. Update MCP_REGISTRATION_API_KEY with the generated key
|
||||
# 4. Build the image from the Dockerfile and run it where the MCP Gateway
|
||||
# can reach it (see README.md)
|
||||
#
|
||||
# MCP GATEWAY INTEGRATION:
|
||||
# When registering with the MCP Gateway, use the URL the Gateway reaches this
|
||||
# server at; for a container on the Gateway's network, its container name:
|
||||
# http://aws-discovery:8112
|
||||
# ============================================
|
||||
|
||||
# Server Identity
|
||||
MCP_SERVER_NAME=AWS Discovery
|
||||
MCP_SERVER_ID=aws-discovery
|
||||
MCP_SERVER_VERSION=0.1.1
|
||||
|
||||
# Server Configuration
|
||||
MCP_SERVER_PORT=8112
|
||||
|
||||
# Logging: level (DEBUG, INFO, WARNING, ERROR) and format
|
||||
# (json = one object per line, for log stores; console = for reading by eye)
|
||||
LOG_LEVEL=INFO
|
||||
LOG_FORMAT=json
|
||||
|
||||
# ============================================
|
||||
# AUTHENTICATION (REQUIRED for production!)
|
||||
# ============================================
|
||||
# This key authenticates MCP Gateway requests to this server.
|
||||
# The Gateway stores this key and includes it in all tool/call requests.
|
||||
#
|
||||
# Generate a secure key:
|
||||
# openssl rand -hex 32
|
||||
#
|
||||
# IMPORTANT: Keep this key secret! It's stored in:
|
||||
# - This .env file (gitignored)
|
||||
# - MCP Gateway database (encrypted)
|
||||
MCP_REGISTRATION_API_KEY=<generate one: openssl rand -hex 32>
|
||||
|
||||
# Set to "false" ONLY for local development/testing
|
||||
# WARNING: Disabling auth in production is a security risk!
|
||||
REQUIRE_AUTH=true
|
||||
|
||||
# ============================================
|
||||
# CREDENTIALS FOR THE UPSTREAM (sent with each request, not set here)
|
||||
# ============================================
|
||||
# The MCP Gateway sends the tenant's credential with each call, from the Vault Service.
|
||||
# true: a call without one is refused. Set to false only for local runs, where the
|
||||
# server may use its own environment.
|
||||
REQUIRE_VAULT_CONNECTION=true
|
||||
|
||||
# ============================================
|
||||
# Add your own settings below
|
||||
# ============================================
|
||||
# Credentials for the upstream are not set here: the gateway sends them with each request.
|
||||
# EXAMPLE_SETTING=value
|
||||
15
mcp-servers/aws-discovery/.gitignore
vendored
Normal file
15
mcp-servers/aws-discovery/.gitignore
vendored
Normal file
@@ -0,0 +1,15 @@
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
.venv/
|
||||
venv/
|
||||
.pytest_cache/
|
||||
|
||||
# Editors
|
||||
.vscode/
|
||||
.idea/
|
||||
47
mcp-servers/aws-discovery/Dockerfile
Normal file
47
mcp-servers/aws-discovery/Dockerfile
Normal file
@@ -0,0 +1,47 @@
|
||||
# MCP Server Dockerfile
|
||||
# Generated by Agent Builder Platform (template 1.1.0)
|
||||
#
|
||||
# Built on the platform's MCP server base image: Chainguard Python with the
|
||||
# packages in requirements.txt already installed, a non-root user (1000) and
|
||||
# no pip. This image adds only the server's own files.
|
||||
#
|
||||
# docker build -t <server>:<version> .
|
||||
# docker build --build-arg BASE_IMAGE=<local base image> -t ... .
|
||||
ARG BASE_IMAGE=kyndryl.jfrog.io/kc-ai-agent-factory-docker-local/mcp-server-base:1.1.0
|
||||
|
||||
# Stage 1: the server's extra Python packages, if requirements.txt lists any.
|
||||
# The base image's build image (<base image>-build: the base image plus uv) installs
|
||||
# them with its vendor-install script: only the packages added go on to
|
||||
# /vendor, and one that would change a package the base image already has stops
|
||||
# the build. uv never reaches the server's image.
|
||||
FROM ${BASE_IMAGE}-build AS vendor
|
||||
COPY requirements.txt constraints.txt /tmp/
|
||||
RUN vendor-install /tmp/requirements.txt /vendor /tmp/constraints.txt
|
||||
|
||||
# Stage 2: the server: the base image, its extra packages and its files.
|
||||
FROM ${BASE_IMAGE}
|
||||
|
||||
LABEL maintainer="Agent Builder Platform"
|
||||
LABEL description="Read-only discovery of a customer's AWS estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Trusted Advisor findings."
|
||||
LABEL version="0.1.1"
|
||||
LABEL server.id="aws-discovery"
|
||||
LABEL template.version="1.1.0"
|
||||
|
||||
COPY --from=vendor /vendor /app/vendor/
|
||||
COPY server.py mcp_connection.py /app/
|
||||
|
||||
# Environment
|
||||
# The ConfigMap's SERVER_PORT overrides this, so the container, Service and probes agree
|
||||
ENV SERVER_PORT=8112
|
||||
ENV LOG_LEVEL=INFO
|
||||
ENV LOG_FORMAT=json
|
||||
|
||||
# Expose port
|
||||
EXPOSE 8112
|
||||
|
||||
# Health check
|
||||
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
||||
CMD python -c "import os, urllib.request; urllib.request.urlopen('http://localhost:%s/health' % (os.getenv('MCP_SERVER_PORT') or os.getenv('SERVER_PORT') or '8112'))" || exit 1
|
||||
|
||||
# Run the server
|
||||
CMD ["python", "server.py"]
|
||||
204
mcp-servers/aws-discovery/README.md
Normal file
204
mcp-servers/aws-discovery/README.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# AWS Discovery
|
||||
|
||||
Read-only discovery of a customer's AWS estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Trusted Advisor findings.
|
||||
|
||||
**Version:** 0.1.1
|
||||
**Server ID:** aws-discovery
|
||||
**Port:** 8112
|
||||
|
||||
---
|
||||
|
||||
## 🚀 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>:8112`.
|
||||
|
||||
### 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_list_accounts**: List the organisation's accounts or organizational units. Needs the management or a delegated administrator account.
|
||||
- **aws_list_resources**: List resources of one type that AWS Config has recorded.
|
||||
- **aws_query_resources**: Run a read-only AWS Config advanced query. Uses the organisation aggregator when the connection names one.
|
||||
- **aws_get_resource_metadata**: Read-only provider metadata for one resource, from AWS Config.
|
||||
- **aws_list_servers**: List EC2 instances, Auto Scaling groups or EBS volumes.
|
||||
- **aws_list_workloads**: List Lambda functions, ECS clusters, App Runner services or Elastic Beanstalk environments. Environment variables are removed.
|
||||
- **aws_list_kubernetes_clusters**: List EKS clusters with version, node groups and networking. Stops at the cloud control plane.
|
||||
- **aws_get_network_topology**: List VPCs, subnets, route tables, security groups, NAT or internet gateways, transit gateways, peerings, endpoints or load balancers.
|
||||
- **aws_list_data_stores**: List RDS instances, DynamoDB tables or S3 buckets. Metadata only, never rows or objects.
|
||||
- **aws_list_organization_policies**: List Organizations policies with their documents, or Config rule compliance.
|
||||
- **aws_list_resource_policies**: List resource-based policies: S3 buckets, KMS keys, Lambda functions, SQS queues, SNS topics, or IAM role trust policies. People are anonymised.
|
||||
- **aws_list_recommendations**: List Trusted Advisor recommendations, each with a common Well-Architected pillar, or the customer's existing Well-Architected Tool reviews.
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Authentication
|
||||
|
||||
This server uses Bearer token authentication for MCP protocol messages.
|
||||
|
||||
```bash
|
||||
# Test with authentication
|
||||
curl -X POST http://localhost:8112/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:8112`)
|
||||
- **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 | no |
|
||||
| `secret_access_key` | yes | yes |
|
||||
| `role_arn` | yes | no |
|
||||
| `external_id` | yes | yes |
|
||||
| `regions` | yes | no |
|
||||
| `account_ids` | no | no |
|
||||
| `member_role_name` | no | no |
|
||||
| `aggregator_name` | no | no |
|
||||
|
||||
- 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:8112 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 `aws-discovery/`, then add it to
|
||||
`mcp_servers_to_deploy.yaml` in that repository with the instances it should
|
||||
run on:
|
||||
|
||||
```yaml
|
||||
- name: "aws-discovery"
|
||||
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:8112/health
|
||||
|
||||
# List tools
|
||||
curl -X POST http://localhost:8112/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)
|
||||
29
mcp-servers/aws-discovery/constraints.txt
Normal file
29
mcp-servers/aws-discovery/constraints.txt
Normal file
@@ -0,0 +1,29 @@
|
||||
# Every package installed in a generated MCP server, pinned to one exact version:
|
||||
# the ones requirements.txt names and everything they bring in. They are
|
||||
# installed in the MCP server base image (Dockerfile.base), so every server
|
||||
# built from this template gets the same versions as the platform's own
|
||||
# services.
|
||||
annotated-doc==0.0.5
|
||||
annotated-types==0.8.0
|
||||
anyio==4.15.1
|
||||
certifi==2026.10.19
|
||||
click==8.5.0
|
||||
fastapi==0.143.2
|
||||
h11==0.16.0
|
||||
httpcore==1.0.9
|
||||
httptools==0.9.0
|
||||
httpx==0.28.1
|
||||
idna==3.20
|
||||
opentelemetry-api==1.45.1
|
||||
pydantic==2.14.1
|
||||
pydantic-core==2.50.1
|
||||
python-dotenv==1.2.4
|
||||
pyyaml==6.0.3
|
||||
starlette==1.8.0
|
||||
structlog==26.1.0
|
||||
typing-extensions==4.16.0
|
||||
typing-inspection==0.4.4
|
||||
uvicorn==0.54.0
|
||||
uvloop==0.23.0
|
||||
watchfiles==1.3.0
|
||||
websockets==16.1.1
|
||||
25
mcp-servers/aws-discovery/kubernetes/configmap.yaml
Normal file
25
mcp-servers/aws-discovery/kubernetes/configmap.yaml
Normal file
@@ -0,0 +1,25 @@
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>-config # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
data:
|
||||
|
||||
# Read by the CI/CD pipeline: the server's name, and the port it listens on
|
||||
# (used for the container, the Service and the probes)
|
||||
MCP_SERVER_NAME: "aws-discovery"
|
||||
SERVER_PORT: "8112"
|
||||
|
||||
# One JSON object per line; LOG_FORMAT=console prints readable lines
|
||||
LOG_LEVEL: "INFO"
|
||||
LOG_FORMAT: "json"
|
||||
|
||||
# Leave on. The Gateway authenticates to this server with a bearer token, and
|
||||
# turning this off makes every tool callable by anything that can reach the
|
||||
# pod inside the cluster.
|
||||
REQUIRE_AUTH: "true"
|
||||
|
||||
# Refuse a call that arrives without the tenant's credential from the Vault Service
|
||||
REQUIRE_VAULT_CONNECTION: "true"
|
||||
|
||||
# Add your own settings here
|
||||
# EXAMPLE_SETTING: "value"
|
||||
71
mcp-servers/aws-discovery/kubernetes/deployment.yaml
Normal file
71
mcp-servers/aws-discovery/kubernetes/deployment.yaml
Normal file
@@ -0,0 +1,71 @@
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
imagePullSecrets:
|
||||
- name: jfrog-secret
|
||||
containers:
|
||||
- name: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
image: <placeholder_for_image> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
imagePullPolicy: Always
|
||||
ports:
|
||||
- containerPort: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
name: http
|
||||
# Load all environment variables from ConfigMap
|
||||
envFrom:
|
||||
- secretRef:
|
||||
name: <placeholder_for_mcp_server_name>-secrets # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
optional: true # Won't fail if secret doesn't exist
|
||||
- secretRef:
|
||||
name: <placeholder_for_mcp_server_name>-dotenv-secrets # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
optional: true # Won't fail if secret doesn't exist
|
||||
- configMapRef:
|
||||
name: <placeholder_for_mcp_server_name>-config # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
# The registration key and server id are generated by the CI/CD pipeline;
|
||||
# the server needs the key to accept the Gateway's calls
|
||||
env:
|
||||
- name: MCP_REGISTRATION_API_KEY
|
||||
value: "<placeholder_for_registration_api_key>" # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
- name: MCP_SERVER_ID
|
||||
value: "<placeholder_for_server_id>" # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
resources:
|
||||
requests:
|
||||
memory: "128Mi"
|
||||
cpu: "10m"
|
||||
limits:
|
||||
memory: "1024Mi"
|
||||
cpu: "1000m"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
initialDelaySeconds: 30 # Wait X seconds before first check
|
||||
periodSeconds: 15 # Check every X seconds
|
||||
timeoutSeconds: 10 # Each check can take up to X seconds to respond
|
||||
failureThreshold: 5 # Allow X consecutive failures before marking unhealthy
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
initialDelaySeconds: 30 # Wait X seconds before first check
|
||||
periodSeconds: 15 # Check every X seconds
|
||||
timeoutSeconds: 10 # Each check can take up to X seconds to respond
|
||||
failureThreshold: 5 # Allow X consecutive failures before marking unhealthy
|
||||
|
||||
# volumes:
|
||||
# - name: execution-storage
|
||||
# persistentVolumeClaim:
|
||||
# claimName: execution-storage-pvc # Same PVC name as core-components
|
||||
20
mcp-servers/aws-discovery/kubernetes/kustomization.yaml
Normal file
20
mcp-servers/aws-discovery/kubernetes/kustomization.yaml
Normal file
@@ -0,0 +1,20 @@
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- namespace.yaml
|
||||
- deployment.yaml
|
||||
- service.yaml
|
||||
- configmap.yaml
|
||||
- secretnames.yaml
|
||||
|
||||
# Optionally add common labels
|
||||
|
||||
# Namespace for all resources
|
||||
namespace: mcp-servers
|
||||
labels:
|
||||
- includeSelectors: true
|
||||
pairs:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
environment: production
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
7
mcp-servers/aws-discovery/kubernetes/namespace.yaml
Normal file
7
mcp-servers/aws-discovery/kubernetes/namespace.yaml
Normal file
@@ -0,0 +1,7 @@
|
||||
# Do not modify this file, otherwise CI/CD pipeline will fail
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: mcp-servers
|
||||
labels:
|
||||
name: mcp-servers
|
||||
18
mcp-servers/aws-discovery/kubernetes/secretnames.yaml
Normal file
18
mcp-servers/aws-discovery/kubernetes/secretnames.yaml
Normal file
@@ -0,0 +1,18 @@
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>-secrets
|
||||
type: Opaque
|
||||
data:
|
||||
# Base64 encoded values (NOT RECOMMENDED for sensitive data)
|
||||
# To encode: echo -n 'your-secret-value' | base64
|
||||
# Example: api-key: eW91ci1hcGkta2V5LXZhbHVl
|
||||
|
||||
stringData:
|
||||
# Plain text values saved on GitHub Secrets (RECOMMENDED)
|
||||
# Example:
|
||||
#
|
||||
# DB_PASSWORD: ${DB_PASSWORD_GITHUB_SECRET}
|
||||
# ANOTHER_SECRET: ${ANOTHER_GITHUB_SECRET}
|
||||
#
|
||||
# ${DB_PASSWORD_GITHUB_SECRET} and ${ANOTHER_GITHUB_SECRET} must exist as GitHub Secrets
|
||||
33
mcp-servers/aws-discovery/kubernetes/service.yaml
Normal file
33
mcp-servers/aws-discovery/kubernetes/service.yaml
Normal file
@@ -0,0 +1,33 @@
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name>
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
type: ClusterIP
|
||||
ports:
|
||||
- port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
targetPort: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
protocol: TCP
|
||||
name: http
|
||||
selector:
|
||||
app: <placeholder_for_mcp_server_name>
|
||||
---
|
||||
# Optional: LoadBalancer service for external access
|
||||
# apiVersion: v1
|
||||
# kind: Service
|
||||
# metadata:
|
||||
# name: <placeholder_for_mcp_server_name>-external
|
||||
# labels:
|
||||
# app: <placeholder_for_mcp_server_name>
|
||||
# spec:
|
||||
# type: LoadBalancer
|
||||
# ports:
|
||||
# - port: 80
|
||||
# targetPort: 8080
|
||||
# protocol: TCP
|
||||
# name: http
|
||||
# selector:
|
||||
# app: <placeholder_for_mcp_server_name>
|
||||
256
mcp-servers/aws-discovery/mcp_connection.py
Normal file
256
mcp-servers/aws-discovery/mcp_connection.py
Normal file
@@ -0,0 +1,256 @@
|
||||
"""The connection a request carries: which upstream account this call is for.
|
||||
|
||||
An MCP server that talks to a third-party system needs that system's address and credentials. Taking
|
||||
them from environment variables makes one process serve one account for ever. Here the MCP Gateway
|
||||
sends them with each call, from the Vault Service, in MCP's own `_meta` field, under our vendor prefix:
|
||||
|
||||
initialize result _meta["com.kyndryl.mcp/connection-schema"] what this server needs (JSON Schema)
|
||||
_meta["com.kyndryl.mcp/verify-tool"] the tool that tests a connection
|
||||
tools/call, resources/read, prompts/get
|
||||
params._meta["com.kyndryl.mcp/connection"] the values, matching that schema
|
||||
|
||||
`_meta` is where the specification tells implementations to put their own data, so a client that does
|
||||
not know these keys ignores them. The values never travel in `arguments`, which is what the model
|
||||
writes and reads, so a credential cannot enter the model's context.
|
||||
|
||||
The connection is bound for the life of one request and read with `active()`. It is None when the caller
|
||||
sent nothing; whether the server may then use its own environment is decided in server.py
|
||||
(REQUIRE_VAULT_CONNECTION, which is on by default).
|
||||
|
||||
WHAT IS STANDARD AND WHAT IS OURS
|
||||
---------------------------------
|
||||
The mechanism is standard. `_meta` is the specification's sanctioned place for implementation-specific
|
||||
data, with formal key-naming rules (2026-07-28, "General fields / _meta"):
|
||||
|
||||
Prefix ... SHOULD use reverse DNS notation. Any prefix where the second label is
|
||||
`modelcontextprotocol` or `mcp` is reserved for MCP use ... third-party extensions use their own
|
||||
vendor prefix.
|
||||
|
||||
`com.kyndryl.mcp/` satisfies that: the second label is `kyndryl`, so it is a legitimate vendor prefix and
|
||||
not reserved. A client that does not recognise our keys ignores them, which is exactly what `_meta` is for.
|
||||
The value carried is a *separate* upstream credential, never the caller's own token (the specification
|
||||
says a server MUST NOT pass through the token it received from its client).
|
||||
|
||||
Only the three key names and the shape of their payloads are ours. When SEP-2127 (MCP Server Card) lands,
|
||||
the schema is what moves onto the card, and the key names are the only thing that changes.
|
||||
|
||||
The third key, VERIFY_TOOL_KEY, adds very little. Checking a credential is a plain `tools/call` against an
|
||||
ordinary tool that appears in `tools/list` like any other: no new method, no new transport. The only
|
||||
question that needed answering is WHICH tool, and the alternative was for the gateway to guess by name. A
|
||||
server that advertises nothing here is simply not verifiable.
|
||||
|
||||
STATELESSNESS
|
||||
-------------
|
||||
The 2026-07-28 specification made MCP explicitly stateless: "Servers MUST NOT rely on prior requests over
|
||||
the same connection to establish context ... Every request supplies this metadata in its _meta field."
|
||||
A module-level connection built once at import is exactly the state the specification tells servers not to
|
||||
keep. Binding the connection per request is therefore not only what multi-tenancy needs, it is what the
|
||||
protocol asks for.
|
||||
|
||||
HOW IT IS USED (server.py does all of this; a tool only calls get_connection())
|
||||
------------------------------------------------------------------------------
|
||||
import mcp_connection
|
||||
|
||||
# advertise, in the initialize result
|
||||
result["_meta"] = mcp_connection.schema_meta(CONNECTION_SCHEMA, verify_tool="verify_connection")
|
||||
|
||||
# bind, for the life of one request
|
||||
token = mcp_connection.bind(mcp_connection.from_params(request.params))
|
||||
try:
|
||||
... # mcp_connection.active() anywhere below
|
||||
finally:
|
||||
mcp_connection.unbind(token)
|
||||
|
||||
LOGS AND ERROR MESSAGES
|
||||
-----------------------
|
||||
`scrub()` is applied to every log line, and to the `error` text of a failed tool call, so the connection's
|
||||
values and credential-looking URL parameters (`?key=...`) never leave the process. `redact()` does the
|
||||
connection values alone. Neither is applied to a successful result: a presigned URL a tool returns on
|
||||
purpose must survive.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextvars
|
||||
import hashlib
|
||||
import hmac
|
||||
import json
|
||||
import re
|
||||
import secrets
|
||||
from typing import Any, Callable, Dict, List, Optional
|
||||
|
||||
VENDOR = "com.kyndryl.mcp"
|
||||
SCHEMA_KEY = f"{VENDOR}/connection-schema"
|
||||
CONNECTION_KEY = f"{VENDOR}/connection"
|
||||
VERIFY_TOOL_KEY = f"{VENDOR}/verify-tool"
|
||||
|
||||
_active: contextvars.ContextVar[Optional[Dict[str, Any]]] = contextvars.ContextVar(
|
||||
"mcp_connection", default=None
|
||||
)
|
||||
|
||||
# Per process, so a fingerprint in a log cannot be checked against a guessed credential offline
|
||||
_FINGERPRINT_KEY = secrets.token_bytes(32)
|
||||
|
||||
|
||||
def schema_meta(schema: Dict[str, Any], verify_tool: Optional[str] = None) -> Dict[str, Any]:
|
||||
"""The `_meta` object that advertises `schema` on an initialize result."""
|
||||
meta: Dict[str, Any] = {SCHEMA_KEY: schema}
|
||||
if verify_tool:
|
||||
meta[VERIFY_TOOL_KEY] = verify_tool
|
||||
return meta
|
||||
|
||||
|
||||
def verify_tool_from_initialize(result: Optional[Dict[str, Any]]) -> Optional[str]:
|
||||
"""The verify tool an initialize result advertises, or None.
|
||||
|
||||
The reader half of schema_meta, here rather than in the gateway so the two ends of the key cannot
|
||||
drift apart.
|
||||
"""
|
||||
if not isinstance(result, dict):
|
||||
return None
|
||||
meta = result.get("_meta")
|
||||
if not isinstance(meta, dict):
|
||||
return None
|
||||
name = meta.get(VERIFY_TOOL_KEY)
|
||||
return name if isinstance(name, str) and name.strip() else None
|
||||
|
||||
|
||||
def from_params(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
|
||||
"""The connection in a request's `params._meta`, or None.
|
||||
|
||||
Anything that is not an object counts as absent: a malformed connection must not be more
|
||||
powerful than none at all.
|
||||
"""
|
||||
if not isinstance(params, dict):
|
||||
return None
|
||||
meta = params.get("_meta")
|
||||
if not isinstance(meta, dict):
|
||||
return None
|
||||
profile = meta.get(CONNECTION_KEY)
|
||||
return profile if isinstance(profile, dict) and profile else None
|
||||
|
||||
|
||||
def bind(profile: Optional[Dict[str, Any]]) -> contextvars.Token:
|
||||
"""Make `profile` the connection for this request."""
|
||||
return _active.set(profile)
|
||||
|
||||
|
||||
def unbind(token: contextvars.Token) -> None:
|
||||
try:
|
||||
_active.reset(token)
|
||||
except ValueError:
|
||||
_active.set(None)
|
||||
|
||||
|
||||
def active() -> Optional[Dict[str, Any]]:
|
||||
"""The connection for this request, or None."""
|
||||
return _active.get()
|
||||
|
||||
|
||||
def fingerprint(profile: Optional[Dict[str, Any]]) -> str:
|
||||
"""A short id for a connection, safe to log and to cache on; the credential never is the key."""
|
||||
if not profile:
|
||||
return "env"
|
||||
canonical = json.dumps(profile, sort_keys=True, separators=(",", ":"), default=str)
|
||||
return hmac.new(_FINGERPRINT_KEY, canonical.encode("utf-8"), hashlib.sha256).hexdigest()[:16]
|
||||
|
||||
|
||||
def redact(text: Any) -> str:
|
||||
"""`text` with every value of this request's connection replaced, for logs and error replies.
|
||||
|
||||
A tool can put a credential in an exception message without meaning to. Values shorter than four
|
||||
characters are left alone: replacing them would garble ordinary text.
|
||||
"""
|
||||
result = str(text)
|
||||
values = [v for v in (active() or {}).values() if isinstance(v, str) and len(v) >= 4]
|
||||
for value in sorted(values, key=len, reverse=True):
|
||||
result = result.replace(value, "[redacted]")
|
||||
return result
|
||||
|
||||
|
||||
# Query parameters that carry a credential in the URL of an upstream request
|
||||
_URL_CREDENTIAL = re.compile(
|
||||
r"([?&;](?:api[_-]?key|apikey|key|token|access[_-]?token|auth|secret|password|passwd|"
|
||||
r"client[_-]?secret|appid|app[_-]?id|sig|signature)=)[^&\s\"'#<>]+",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
|
||||
def scrub(value: Any, _depth: int = 0) -> Any:
|
||||
"""`value` with credentials taken out, for anything that is logged or sent back to a caller.
|
||||
|
||||
Strings lose the request's connection values and the value of any credential query parameter in a
|
||||
URL (`?key=...`); dicts, lists and tuples are scrubbed inside. Anything else is returned as it is.
|
||||
Not for tool results in general: a presigned URL a tool returns on purpose would be damaged.
|
||||
"""
|
||||
if isinstance(value, str):
|
||||
return _URL_CREDENTIAL.sub(r"\1[redacted]", redact(value))
|
||||
if _depth > 5:
|
||||
return value
|
||||
if isinstance(value, dict):
|
||||
return {k: scrub(v, _depth + 1) for k, v in value.items()}
|
||||
if isinstance(value, (list, tuple)):
|
||||
return type(value)(scrub(v, _depth + 1) for v in value)
|
||||
return value
|
||||
|
||||
|
||||
def missing_fields(profile: Optional[Dict[str, Any]], schema: Dict[str, Any]) -> List[str]:
|
||||
"""The required fields of `schema` that `profile` does not supply."""
|
||||
if not profile:
|
||||
return []
|
||||
required = schema.get("required") or []
|
||||
return [name for name in required if not str(profile.get(name) or "").strip()]
|
||||
|
||||
|
||||
def install_invalid_request_handler(app: Any, on_invalid: Optional[Callable[[str], None]] = None) -> None:
|
||||
"""Answer a request that is not valid JSON-RPC with a JSON-RPC error that does not repeat the request.
|
||||
|
||||
FastAPI's own answer (HTTP 422) repeats the request body under "input". The body is where the gateway puts
|
||||
the tenant's connection, so a request that is merely malformed (no "id", say) would get the credential back
|
||||
in the reply, and in the log of anything that records replies. The status stays 422; the body is a JSON-RPC
|
||||
error (-32600) that names only the fields at fault. `on_invalid`, if given, is called with that text, already
|
||||
reduced to harmless characters, so the caller can log it in its own style.
|
||||
|
||||
Call it once, right after `app = FastAPI(...)`. FastAPI is imported here, not at module level, so the rest of
|
||||
this module stays importable without it.
|
||||
"""
|
||||
from fastapi.exceptions import RequestValidationError
|
||||
from fastapi.responses import JSONResponse
|
||||
|
||||
@app.exception_handler(RequestValidationError)
|
||||
async def invalid_request(request, exc):
|
||||
names = {
|
||||
"body" if error.get("type") == "json_invalid" else ".".join(str(p) for p in error.get("loc", ())[1:]) or "body"
|
||||
for error in exc.errors()
|
||||
}
|
||||
fields = re.sub(r"[^\w.\-, ]", "?", ", ".join(sorted(names)))[:200]
|
||||
if on_invalid is not None:
|
||||
on_invalid(fields)
|
||||
return JSONResponse(
|
||||
status_code=422,
|
||||
content={
|
||||
"jsonrpc": "2.0",
|
||||
"id": None,
|
||||
"result": None,
|
||||
"error": {"code": -32600, "message": "Invalid request: check " + fields},
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"install_invalid_request_handler",
|
||||
"VENDOR",
|
||||
"SCHEMA_KEY",
|
||||
"CONNECTION_KEY",
|
||||
"VERIFY_TOOL_KEY",
|
||||
"schema_meta",
|
||||
"verify_tool_from_initialize",
|
||||
"from_params",
|
||||
"bind",
|
||||
"unbind",
|
||||
"active",
|
||||
"fingerprint",
|
||||
"redact",
|
||||
"scrub",
|
||||
"missing_fields",
|
||||
]
|
||||
42
mcp-servers/aws-discovery/requirements.txt
Normal file
42
mcp-servers/aws-discovery/requirements.txt
Normal file
@@ -0,0 +1,42 @@
|
||||
# MCP Server Dependencies
|
||||
# Generated by Agent Builder Platform
|
||||
|
||||
# Each dependency is pinned to one exact version, and constraints.txt pins everything they bring
|
||||
# in, so two builds of the same server get the same packages -- the same versions as the
|
||||
# platform's own services. The packages below are already installed in the MCP server base
|
||||
# image the Dockerfile builds on; a package added to this file is installed on top of them at
|
||||
# build time. Changing the version of one the base has stops the build: the base image moves
|
||||
# those, with the template.
|
||||
|
||||
# Core Framework
|
||||
# FastAPI - Modern web framework for MCP server
|
||||
fastapi==0.143.2
|
||||
|
||||
# ASGI Server
|
||||
# Uvicorn - Lightning-fast ASGI server
|
||||
uvicorn[standard]==0.54.0
|
||||
|
||||
# Data Validation
|
||||
# Pydantic - Data validation using Python type hints
|
||||
pydantic==2.14.1
|
||||
|
||||
# HTTP Client
|
||||
# HTTPX - Async HTTP client for API calls
|
||||
httpx==0.28.1
|
||||
|
||||
# Environment Variables
|
||||
# python-dotenv - Load environment from .env files
|
||||
python-dotenv==1.2.4
|
||||
|
||||
# Structured Logging
|
||||
# structlog - JSON log lines (see LOG_FORMAT in server.py)
|
||||
structlog==26.1.0
|
||||
|
||||
# Optional: Add your custom dependencies below
|
||||
# requests>=2.31.0
|
||||
# aiofiles>=23.2.1
|
||||
# sqlalchemy>=2.0.0
|
||||
# redis>=5.0.0
|
||||
|
||||
# Added by this server's definition
|
||||
boto3==1.43.122
|
||||
1458
mcp-servers/aws-discovery/server.py
Normal file
1458
mcp-servers/aws-discovery/server.py
Normal file
File diff suppressed because it is too large
Load Diff
145
mcp-servers/aws-discovery/tests/test_aws.py
Normal file
145
mcp-servers/aws-discovery/tests/test_aws.py
Normal file
@@ -0,0 +1,145 @@
|
||||
import asyncio
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import boto3
|
||||
import pytest
|
||||
from moto import mock_aws
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
||||
import mcp_connection # noqa: E402
|
||||
import server # noqa: E402
|
||||
|
||||
os.environ.setdefault("AWS_DEFAULT_REGION", "eu-west-2")
|
||||
CONNECTION = {"access_key_id": "testing", "secret_access_key": "testing", "external_id": "kab-external-id",
|
||||
"role_arn": "arn:aws:iam::123456789012:role/kab-read-only", "regions": "eu-west-2,eu-west-1",
|
||||
"account_ids": "222222222222", "member_role_name": "kab-read-only"}
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def aws():
|
||||
with mock_aws():
|
||||
server.AWS_SESSIONS.clear()
|
||||
yield
|
||||
|
||||
|
||||
def call(tool, arguments=None):
|
||||
async def run():
|
||||
bound = mcp_connection.bind(CONNECTION)
|
||||
try:
|
||||
return await getattr(server, tool)(arguments or {})
|
||||
finally:
|
||||
mcp_connection.unbind(bound)
|
||||
|
||||
return asyncio.run(run())
|
||||
|
||||
|
||||
def client(service, region="eu-west-2"):
|
||||
return boto3.client(service, region_name=region, aws_access_key_id="testing", aws_secret_access_key="testing")
|
||||
|
||||
|
||||
def test_check_connection(aws):
|
||||
result = call("aws_check_connection")
|
||||
assert result["ok"] is True and result["account"]
|
||||
|
||||
|
||||
def test_servers_and_owner_tag(aws):
|
||||
ec2 = client("ec2")
|
||||
image = ec2.describe_images()["Images"][0]["ImageId"]
|
||||
ec2.run_instances(ImageId=image, MinCount=1, MaxCount=1, UserData="c2VjcmV0",
|
||||
TagSpecifications=[{"ResourceType": "instance", "Tags": [{"Key": "Owner", "Value": "Ana"}, {"Key": "Name", "Value": "web-01"}]}])
|
||||
result = call("aws_list_servers")
|
||||
text = json.dumps(result)
|
||||
assert result["data"]["count"] == 1 and "web-01" in text and '"Ana"' not in text
|
||||
|
||||
|
||||
def test_networks_and_subnets(aws):
|
||||
ec2 = client("ec2")
|
||||
vpc = ec2.create_vpc(CidrBlock="10.9.0.0/16")["Vpc"]["VpcId"]
|
||||
ec2.create_subnet(VpcId=vpc, CidrBlock="10.9.1.0/24")
|
||||
assert vpc in json.dumps(call("aws_get_network_topology", {"kind": "vpcs"}))
|
||||
assert "10.9.1.0/24" in json.dumps(call("aws_get_network_topology", {"kind": "subnets"}))
|
||||
|
||||
|
||||
def test_each_region_is_read_separately(aws):
|
||||
client("ec2", "eu-west-1").create_vpc(CidrBlock="10.8.0.0/16")
|
||||
assert "10.8.0.0/16" in json.dumps(call("aws_get_network_topology", {"region": "eu-west-1"}))
|
||||
assert "10.8.0.0/16" not in json.dumps(call("aws_get_network_topology", {"region": "eu-west-2"}))
|
||||
|
||||
|
||||
def test_region_outside_the_connection_is_refused(aws):
|
||||
assert call("aws_list_servers", {"region": "us-east-1"})["error"]["code"] == "outside_scope"
|
||||
|
||||
|
||||
def test_account_outside_the_connection_is_refused(aws):
|
||||
assert call("aws_list_servers", {"account_id": "999999999999"})["error"]["code"] == "outside_scope"
|
||||
|
||||
|
||||
def test_listed_member_account_is_assumed(aws):
|
||||
assert call("aws_list_servers", {"account_id": "222222222222"})["success"] is True
|
||||
|
||||
|
||||
def test_data_stores(aws):
|
||||
client("s3").create_bucket(Bucket="orders", CreateBucketConfiguration={"LocationConstraint": "eu-west-2"})
|
||||
assert "orders" in json.dumps(call("aws_list_data_stores", {"kind": "s3_buckets"}))
|
||||
|
||||
|
||||
def test_lambda_environment_is_removed(aws):
|
||||
role = client("iam").create_role(RoleName="fn", AssumeRolePolicyDocument="{}")["Role"]["Arn"]
|
||||
client("lambda").create_function(FunctionName="f", Runtime="python3.12", Role=role, Handler="a.b",
|
||||
Code={"ZipFile": b"x"}, Environment={"Variables": {"DB_PASSWORD": "hunter2"}})
|
||||
assert "hunter2" not in json.dumps(call("aws_list_workloads"))
|
||||
|
||||
|
||||
def test_bucket_policy_principals_are_anonymised(aws):
|
||||
s3 = client("s3")
|
||||
s3.create_bucket(Bucket="kab-test-one", CreateBucketConfiguration={"LocationConstraint": "eu-west-2"})
|
||||
s3.put_bucket_policy(Bucket="kab-test-one", Policy=json.dumps({"Version": "2012-10-17", "Statement": [{
|
||||
"Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::123456789012:user/ana"},
|
||||
"Action": "s3:GetObject", "Resource": "arn:aws:s3:::kab-test-one/*"}]}))
|
||||
item = call("aws_list_resource_policies", {"kind": "s3_buckets"})["data"]["items"][0]
|
||||
assert item["layer"] == "resource" and item["document"]["Statement"][0]["Effect"] == "Allow"
|
||||
assert item["document"]["Statement"][0]["Principal"]["AWS"] == "[user]"
|
||||
|
||||
|
||||
def test_a_bucket_without_a_policy_is_reported_not_fatal(aws):
|
||||
client("s3").create_bucket(Bucket="kab-test-two", CreateBucketConfiguration={"LocationConstraint": "eu-west-2"})
|
||||
items = call("aws_list_resource_policies", {"kind": "s3_buckets"})["data"]["items"]
|
||||
assert items[0]["unread"]
|
||||
|
||||
|
||||
def test_role_trust_policies_keep_roles(aws):
|
||||
client("iam").create_role(RoleName="ops", AssumeRolePolicyDocument=json.dumps({"Statement": [{
|
||||
"Effect": "Allow", "Principal": {"Service": "ec2.amazonaws.com"}, "Action": "sts:AssumeRole"}]}))
|
||||
assert "ec2.amazonaws.com" in json.dumps(call("aws_list_resource_policies", {"kind": "iam_role_trust"}))
|
||||
|
||||
|
||||
def test_kubernetes_clusters(aws):
|
||||
role = client("iam").create_role(RoleName="eks", AssumeRolePolicyDocument="{}")["Role"]["Arn"]
|
||||
client("eks").create_cluster(name="prod", roleArn=role, resourcesVpcConfig={"subnetIds": ["subnet-1"]})
|
||||
item = call("aws_list_kubernetes_clusters")["data"]["items"][0]
|
||||
assert item["name"] == "prod" and "nodegroups" in item
|
||||
|
||||
|
||||
def test_service_control_policies(aws):
|
||||
org = client("organizations", "us-east-1")
|
||||
org.create_organization(FeatureSet="ALL")
|
||||
org.create_policy(Name="deny-root", Description="d", Type="SERVICE_CONTROL_POLICY",
|
||||
Content=json.dumps({"Version": "2012-10-17", "Statement": [{"Effect": "Deny", "Action": "*", "Resource": "*"}]}))
|
||||
items = call("aws_list_organization_policies")["data"]["items"]
|
||||
named = [i for i in items if i.get("name") == "deny-root"]
|
||||
assert named and named[0]["layer"] == "organisation" and named[0]["document"]["Statement"][0]["Effect"] == "Deny"
|
||||
|
||||
|
||||
def test_config_query_must_be_a_select(aws):
|
||||
assert call("aws_query_resources", {"query": "DELETE FROM x"})["error"]["code"] == "invalid_argument"
|
||||
|
||||
|
||||
def test_unknown_kind_lists_the_options(aws):
|
||||
assert "vpcs" in call("aws_get_network_topology", {"kind": "nope"})["error"]["message"]
|
||||
|
||||
|
||||
def test_clients_retry_adaptively():
|
||||
assert 'mode": "adaptive"' in (Path(__file__).resolve().parents[1] / "server.py").read_text()
|
||||
360
mcp-servers/aws-discovery/tests/test_conformance.py
Normal file
360
mcp-servers/aws-discovery/tests/test_conformance.py
Normal file
@@ -0,0 +1,360 @@
|
||||
"""Conformance checks for an MCP server that takes its upstream credentials from the MCP Gateway.
|
||||
|
||||
Run these against a running server before you push it. They need only `pytest` and `httpx`, import
|
||||
nothing from the server and talk to it over HTTP, so they work on a server from the MCP Server
|
||||
Builder and on one written by hand.
|
||||
|
||||
pip install pytest httpx
|
||||
MCP_SERVER_URL=http://localhost:8100 MCP_REGISTRATION_API_KEY=<the server's key> pytest tests/ -v
|
||||
|
||||
What is checked, and why:
|
||||
|
||||
Protocol the server answers /health, refuses callers without its key, and speaks JSON-RPC
|
||||
correctly (initialize, tools/list, ids echoed, errors as errors).
|
||||
Connection a server that needs an upstream account says so in its initialize result
|
||||
(`_meta["com.kyndryl.mcp/connection-schema"]`) and takes the account from each
|
||||
request (`params._meta["com.kyndryl.mcp/connection"]`), not from its own environment.
|
||||
Such a server refuses a call that carries none (fail closed), reports which required
|
||||
field is missing, takes nothing from `arguments`, and never repeats a credential in a
|
||||
reply (the values of fields marked `writeOnly`; every value if none is marked). A server that needs no account skips these checks.
|
||||
|
||||
Settings (environment variables):
|
||||
|
||||
MCP_SERVER_URL default http://localhost:8100
|
||||
MCP_REGISTRATION_API_KEY the key the server was started with (required unless the
|
||||
server has authentication switched off)
|
||||
CONFORMANCE_EXPECT_FAIL_CLOSED default true. Set false only for a server you run locally
|
||||
with REQUIRE_VAULT_CONNECTION=false, so that checks which
|
||||
need a refusal are skipped rather than failed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import secrets
|
||||
import uuid
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
VENDOR = "com.kyndryl.mcp"
|
||||
SCHEMA_KEY = f"{VENDOR}/connection-schema"
|
||||
VERIFY_TOOL_KEY = f"{VENDOR}/verify-tool"
|
||||
CONNECTION_KEY = f"{VENDOR}/connection"
|
||||
|
||||
BASE_URL = os.getenv("MCP_SERVER_URL", "http://localhost:8100").rstrip("/")
|
||||
API_KEY = os.getenv("MCP_REGISTRATION_API_KEY", "")
|
||||
EXPECT_FAIL_CLOSED = os.getenv("CONFORMANCE_EXPECT_FAIL_CLOSED", "true").strip().lower() != "false"
|
||||
|
||||
# A value no server could contain by accident, so finding it in a reply means the server repeated it.
|
||||
SENTINEL = f"sentinel-{secrets.token_hex(6)}"
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ helpers
|
||||
|
||||
|
||||
def auth_headers(key: Optional[str] = None) -> Dict[str, str]:
|
||||
key = API_KEY if key is None else key
|
||||
return {"Authorization": f"Bearer {key}"} if key else {}
|
||||
|
||||
|
||||
def rpc(
|
||||
client: httpx.Client,
|
||||
method: str,
|
||||
params: Optional[Dict[str, Any]] = None,
|
||||
*,
|
||||
request_id: Any = "1",
|
||||
headers: Optional[Dict[str, str]] = None,
|
||||
) -> httpx.Response:
|
||||
return client.post(
|
||||
"/messages",
|
||||
json={"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}},
|
||||
headers=auth_headers() if headers is None else headers,
|
||||
)
|
||||
|
||||
|
||||
def result_of(client: httpx.Client, method: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
||||
response = rpc(client, method, params)
|
||||
assert response.status_code == 200, f"{method} answered HTTP {response.status_code}: {response.text[:300]}"
|
||||
body = response.json()
|
||||
assert not body.get("error"), f"{method} returned an error: {body['error']}"
|
||||
return body["result"]
|
||||
|
||||
|
||||
def with_connection(params: Dict[str, Any], connection: Optional[Dict[str, Any]]) -> Dict[str, Any]:
|
||||
if connection is None:
|
||||
return params
|
||||
return {**params, "_meta": {CONNECTION_KEY: connection}}
|
||||
|
||||
|
||||
def value_for(name: str, spec: Dict[str, Any]) -> Any:
|
||||
"""A value of the right shape for a connection field, carrying the sentinel."""
|
||||
kind = spec.get("type", "string")
|
||||
if kind == "string" and spec.get("format") == "uri":
|
||||
return f"https://{SENTINEL}.invalid"
|
||||
if kind == "integer":
|
||||
return 12345
|
||||
if kind == "boolean":
|
||||
return True
|
||||
return f"{SENTINEL}-{name}"
|
||||
|
||||
|
||||
def full_connection(schema: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return {name: value_for(name, spec) for name, spec in (schema.get("properties") or {}).items()}
|
||||
|
||||
|
||||
def secret_values(schema: Dict[str, Any]) -> List[str]:
|
||||
"""The sent values that must never come back: those of fields marked secret (`writeOnly`).
|
||||
|
||||
A tool may repeat a base URL or a region. If the server marks no field secret, every value is
|
||||
treated as one, because then nothing says which are safe to repeat.
|
||||
"""
|
||||
connection = full_connection(schema)
|
||||
properties = schema.get("properties") or {}
|
||||
marked = [n for n, spec in properties.items() if spec.get("writeOnly")]
|
||||
return [str(connection[n]) for n in (marked or list(properties))]
|
||||
|
||||
|
||||
def repeated(response: httpx.Response, schema: Dict[str, Any]) -> List[str]:
|
||||
return [v for v in secret_values(schema) if v in response.text]
|
||||
|
||||
|
||||
def _string_values(node: Any) -> List[str]:
|
||||
"""Every string anywhere in a JSON value."""
|
||||
if isinstance(node, str):
|
||||
return [node]
|
||||
if isinstance(node, dict):
|
||||
return [v for item in node.values() for v in _string_values(item)]
|
||||
if isinstance(node, list):
|
||||
return [v for item in node for v in _string_values(item)]
|
||||
return []
|
||||
|
||||
|
||||
def call(client: httpx.Client, tool: str, connection: Optional[Dict[str, Any]], arguments: Optional[Dict] = None):
|
||||
return rpc(client, "tools/call", with_connection({"name": tool, "arguments": arguments or {}}, connection))
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ fixtures
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def client():
|
||||
with httpx.Client(base_url=BASE_URL, timeout=30.0) as session:
|
||||
try:
|
||||
session.get("/health")
|
||||
except httpx.HTTPError as error:
|
||||
pytest.exit(f"Cannot reach the server at {BASE_URL}: {error}. Start it, or set MCP_SERVER_URL.", 2)
|
||||
yield session
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def initialize(client) -> Dict[str, Any]:
|
||||
return result_of(client, "initialize", {"protocolVersion": "1.0.0", "clientInfo": {"name": "conformance"}})
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def tools(client) -> List[Dict[str, Any]]:
|
||||
return result_of(client, "tools/list")["tools"]
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def schema(initialize) -> Optional[Dict[str, Any]]:
|
||||
return (initialize.get("_meta") or {}).get(SCHEMA_KEY)
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def needs_connection(schema) -> Dict[str, Any]:
|
||||
if not schema or not schema.get("properties"):
|
||||
pytest.skip("the server advertises no connection fields, so it takes no per-request credentials")
|
||||
return schema
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def probe_tool(initialize, tools) -> str:
|
||||
"""The tool to call in the connection checks: the verify tool when there is one."""
|
||||
verify = (initialize.get("_meta") or {}).get(VERIFY_TOOL_KEY)
|
||||
if verify:
|
||||
return verify
|
||||
assert tools, "the server lists no tools to call"
|
||||
return tools[0]["name"]
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ protocol
|
||||
|
||||
|
||||
def test_health_answers(client):
|
||||
assert client.get("/health").status_code == 200
|
||||
|
||||
|
||||
def test_the_public_auth_endpoint_reveals_no_key(client):
|
||||
response = client.get("/.well-known/mcp-auth")
|
||||
if response.status_code == 404:
|
||||
pytest.skip("the server has no /.well-known/mcp-auth endpoint")
|
||||
assert response.status_code == 200
|
||||
if API_KEY:
|
||||
# A value that equals the key is always a leak. A short key can also appear inside ordinary words
|
||||
# ("nc" in "auth_required"), so searching the text for it is only meaningful for a real-length key.
|
||||
assert API_KEY not in _string_values(response.json()), "/.well-known/mcp-auth returns the server's key"
|
||||
if len(API_KEY) >= 12:
|
||||
assert API_KEY not in response.text, "/.well-known/mcp-auth returns the server's key"
|
||||
|
||||
|
||||
def test_a_call_without_the_servers_key_is_refused(client):
|
||||
response = rpc(client, "tools/list", headers={})
|
||||
assert response.status_code in (401, 403), f"answered HTTP {response.status_code} to a caller with no key"
|
||||
|
||||
|
||||
def test_a_call_with_the_wrong_key_is_refused(client):
|
||||
response = rpc(client, "tools/list", headers=auth_headers("not-the-key-" + uuid.uuid4().hex))
|
||||
assert response.status_code in (401, 403), f"answered HTTP {response.status_code} to a caller with the wrong key"
|
||||
|
||||
|
||||
def test_initialize_describes_the_server(initialize):
|
||||
assert initialize["serverInfo"]["name"]
|
||||
assert isinstance(initialize.get("capabilities"), dict)
|
||||
|
||||
|
||||
def test_tools_have_a_name_a_description_and_an_object_schema(tools):
|
||||
assert isinstance(tools, list)
|
||||
names = [t["name"] for t in tools]
|
||||
assert len(names) == len(set(names)), "two tools share a name"
|
||||
for tool in tools:
|
||||
assert tool["name"] and tool.get("description"), f"tool {tool.get('name')!r} lacks a name or description"
|
||||
assert tool["inputSchema"]["type"] == "object", f"{tool['name']} has no object inputSchema"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("request_id", ["conformance-1", 7])
|
||||
def test_the_reply_echoes_the_request_id(client, request_id):
|
||||
response = rpc(client, "tools/list", request_id=request_id)
|
||||
assert response.status_code == 200
|
||||
assert response.json()["id"] == request_id
|
||||
|
||||
|
||||
def test_an_unknown_method_is_an_error_not_a_crash(client):
|
||||
response = rpc(client, "no/such/method")
|
||||
assert response.status_code == 200
|
||||
assert response.json().get("error"), "an unknown method returned no error"
|
||||
|
||||
|
||||
def test_an_unknown_tool_is_an_error_not_a_crash(client):
|
||||
response = rpc(client, "tools/call", {"name": f"no_such_tool_{uuid.uuid4().hex[:8]}", "arguments": {}})
|
||||
assert response.status_code == 200
|
||||
assert response.json().get("error"), "an unknown tool returned no error"
|
||||
|
||||
|
||||
def test_arguments_that_are_not_an_object_are_the_callers_mistake(client, tools, schema):
|
||||
params = {"name": tools[0]["name"], "arguments": ["not", "an", "object"]}
|
||||
# With a connection, when the server wants one: a refusal for lacking it would answer -32602 too
|
||||
response = rpc(client, "tools/call", with_connection(params, full_connection(schema) if schema else None))
|
||||
assert response.status_code == 200
|
||||
error = response.json().get("error")
|
||||
assert error and error.get("code") == -32602, f"expected invalid params (-32602), got: {response.text[:300]}"
|
||||
|
||||
|
||||
def test_an_invalid_request_does_not_repeat_what_it_carried():
|
||||
# No "id": the request is not valid JSON-RPC, and what it carried (a connection) must not come back.
|
||||
# It has a connection of its own: a server that answers a bad request by dropping the connection (an
|
||||
# unhandled error makes uvicorn do that) must not make the NEXT check fail with "connection reset".
|
||||
marker = f"{SENTINEL}-carried"
|
||||
try:
|
||||
response = httpx.post(
|
||||
f"{BASE_URL}/messages",
|
||||
json={"jsonrpc": "2.0", "method": "tools/list", "params": {"_meta": {CONNECTION_KEY: {"field": marker}}}},
|
||||
headers=auth_headers(),
|
||||
timeout=30.0,
|
||||
)
|
||||
except httpx.TransportError:
|
||||
return # nothing came back, so nothing was repeated
|
||||
assert marker not in response.text, "the reply to an invalid request repeated the request"
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ connection
|
||||
|
||||
|
||||
def test_the_connection_schema_is_a_json_schema_object(needs_connection):
|
||||
assert needs_connection["type"] == "object"
|
||||
properties = needs_connection["properties"]
|
||||
assert isinstance(properties, dict) and properties
|
||||
assert set(needs_connection.get("required", [])) <= set(properties), "a required field is not a property"
|
||||
|
||||
|
||||
def test_the_verify_tool_is_listed(initialize, tools, needs_connection):
|
||||
verify = (initialize.get("_meta") or {}).get(VERIFY_TOOL_KEY)
|
||||
assert verify, f"initialize does not name a verify tool in _meta[{VERIFY_TOOL_KEY!r}]"
|
||||
assert verify in [t["name"] for t in tools], f"the verify tool {verify!r} is not in tools/list"
|
||||
|
||||
|
||||
def test_a_call_with_no_connection_is_refused(client, needs_connection, probe_tool):
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
response = call(client, probe_tool, None)
|
||||
assert response.json().get("error"), (
|
||||
"a call with no connection was served. The server is using its own environment for the "
|
||||
"upstream account, so every tenant would share one. Refuse it (REQUIRE_VAULT_CONNECTION)."
|
||||
)
|
||||
|
||||
|
||||
def test_a_connection_in_the_arguments_is_not_accepted(client, needs_connection, probe_tool):
|
||||
"""The credential travels in `_meta`, which the model never sees; one in `arguments` is not one."""
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
response = call(client, probe_tool, None, arguments=full_connection(needs_connection))
|
||||
assert response.json().get("error"), "a connection passed as tool arguments was accepted"
|
||||
assert not repeated(response, needs_connection), "the reply repeats a credential that was sent as an argument"
|
||||
|
||||
|
||||
def test_a_call_with_a_connection_is_not_refused_for_lacking_one(client, needs_connection, probe_tool):
|
||||
response = call(client, probe_tool, full_connection(needs_connection))
|
||||
assert response.status_code == 200
|
||||
error = response.json().get("error") or {}
|
||||
message = str(error.get("message", "")).lower()
|
||||
assert "no connection" not in message and "missing" not in message, (
|
||||
f"a complete connection was refused as incomplete: {error}"
|
||||
)
|
||||
|
||||
|
||||
def test_an_incomplete_connection_names_what_is_missing(client, needs_connection, probe_tool):
|
||||
required = list(needs_connection.get("required", []))
|
||||
if not required:
|
||||
pytest.skip("no field is required")
|
||||
connection = full_connection(needs_connection)
|
||||
dropped = required[-1]
|
||||
connection.pop(dropped)
|
||||
if not connection:
|
||||
# The only field is required, and an empty connection counts as none. Send one that has a value
|
||||
# but not the field, which is what a mistyped field name in the credential looks like.
|
||||
connection = {"not_a_field_of_this_server": "x"}
|
||||
|
||||
response = call(client, probe_tool, connection)
|
||||
error = response.json().get("error")
|
||||
assert error, f"a connection without the required field {dropped!r} was served"
|
||||
assert dropped in str(error.get("message", "")), f"the refusal does not name the missing field {dropped!r}: {error}"
|
||||
assert not repeated(response, needs_connection), "the refusal repeats a credential value"
|
||||
|
||||
|
||||
def test_no_reply_repeats_the_credential(client, needs_connection, probe_tool, tools):
|
||||
connection = full_connection(needs_connection)
|
||||
replies = [call(client, probe_tool, connection)]
|
||||
for tool in tools[:5]:
|
||||
replies.append(call(client, tool["name"], connection, arguments={"conformance": "probe"}))
|
||||
replies.append(call(client, "no_such_tool", connection))
|
||||
for response in replies:
|
||||
assert not repeated(response, needs_connection), f"a reply repeats the credential: {response.text[:300]}"
|
||||
|
||||
|
||||
def test_a_malformed_connection_is_no_better_than_none(client, needs_connection, probe_tool):
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
for bad in ("just-a-string", ["a", "list"], 42):
|
||||
params = {"name": probe_tool, "arguments": {}, "_meta": {CONNECTION_KEY: bad}}
|
||||
body = rpc(client, "tools/call", params).json()
|
||||
assert body.get("error"), f"a connection of type {type(bad).__name__} was served"
|
||||
|
||||
|
||||
def test_resources_and_prompts_are_listed_when_advertised(client, initialize):
|
||||
capabilities = initialize.get("capabilities") or {}
|
||||
if capabilities.get("resources"):
|
||||
assert isinstance(result_of(client, "resources/list")["resources"], list)
|
||||
if capabilities.get("prompts"):
|
||||
assert isinstance(result_of(client, "prompts/list")["prompts"], list)
|
||||
242
mcp-servers/azure-discovery.server.yaml
Normal file
242
mcp-servers/azure-discovery.server.yaml
Normal file
@@ -0,0 +1,242 @@
|
||||
# Read-only discovery of a customer's Azure estate. Render with scripts/render_mcp_server.py.
|
||||
# Credentials arrive per call from the Vault Service. Store them per project, never tenant-wide.
|
||||
|
||||
server_id: azure-discovery
|
||||
name: Azure Discovery
|
||||
description: Read-only discovery of a customer's Azure estate - servers, workloads, Kubernetes clusters, networks,
|
||||
data stores, policies and Advisor findings - through Azure Resource Graph.
|
||||
version: 0.1.2
|
||||
port: 8111
|
||||
verify_tool: azure_check_connection
|
||||
shared_code:
|
||||
- _common/tool_support.py
|
||||
- _common/azure_support.py
|
||||
connection_fields:
|
||||
- name: tenant_id
|
||||
title: Tenant ID
|
||||
description: The customer's Microsoft Entra tenant id.
|
||||
required: false
|
||||
secret: false
|
||||
- name: client_id
|
||||
title: Client ID
|
||||
description: The application (client) id of the read-only app registration.
|
||||
required: false
|
||||
secret: false
|
||||
- name: client_secret
|
||||
title: Client secret
|
||||
description: The app registration's client secret.
|
||||
required: false
|
||||
secret: true
|
||||
- name: access_token
|
||||
title: Access token
|
||||
description: For a short trial only, instead of the three fields above. A token from az account get-access-token. It expires within about an hour and carries that person's own Azure permissions.
|
||||
required: false
|
||||
secret: true
|
||||
- name: scope_root
|
||||
title: Scope root
|
||||
description: 'What may be read: managementGroups/<id> or subscriptions/<id>.'
|
||||
required: true
|
||||
secret: false
|
||||
- name: cloud
|
||||
title: Cloud
|
||||
description: public, usgov or china. Default public.
|
||||
required: false
|
||||
secret: false
|
||||
tools:
|
||||
- name: azure_check_connection
|
||||
display_name: Check connection
|
||||
description: 'Test the stored connection: sign in and read the scope root. Returns no customer data.'
|
||||
parameters: []
|
||||
ai_implementation: |
|
||||
async def azure_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
try:
|
||||
body = await _azure_graph("ResourceContainers | summarize count()", 1)
|
||||
except Exception as error:
|
||||
return {"ok": False, "message": _upstream_failed("azure", error)["error"]["message"]}
|
||||
return {"ok": True, "message": "Signed in and read the scope root."}
|
||||
- name: azure_list_accounts
|
||||
display_name: List accounts
|
||||
description: 'List the estate structure: management groups, subscriptions and resource groups.'
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: subscriptions, management_groups, resource_groups.'
|
||||
required: false
|
||||
- &id001
|
||||
name: page_size
|
||||
type: integer
|
||||
description: Items per page, up to 200. Default 50.
|
||||
required: false
|
||||
- &id002
|
||||
name: page_token
|
||||
type: string
|
||||
description: next_page_token from the previous reply.
|
||||
required: false
|
||||
ai_implementation: |
|
||||
async def azure_list_accounts(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
kinds = {"subscriptions": ["microsoft.resources/subscriptions"], "management_groups": ["microsoft.management/managementgroups"], "resource_groups": ["microsoft.resources/subscriptions/resourcegroups"]}
|
||||
return await _azure_kind("azure_list_accounts", arguments, kinds, "ResourceContainers", "subscriptions")
|
||||
- name: azure_list_resources
|
||||
display_name: List resources
|
||||
description: List every resource in scope, or one resource type, with id, type, location and tags.
|
||||
parameters:
|
||||
- name: resource_type
|
||||
type: string
|
||||
description: Optional ARM type, such as microsoft.compute/virtualmachines.
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def azure_list_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
kind = arguments.get("resource_type")
|
||||
if kind and not re.fullmatch(r"[A-Za-z0-9./]+", str(kind)):
|
||||
return _refuse("invalid_argument", "resource_type must be an ARM type")
|
||||
where = f" | where type =~ '{kind}'" if kind else ""
|
||||
return await _azure_page("azure_list_resources", arguments, f"Resources{where} | project id, name, type, location, resourceGroup, subscriptionId, tags | order by id asc")
|
||||
- name: azure_query_resources
|
||||
display_name: Query resources
|
||||
description: Run a read-only Azure Resource Graph KQL query over the connection's scope. Secrets and people are
|
||||
removed from the results.
|
||||
parameters:
|
||||
- name: query
|
||||
type: string
|
||||
description: KQL starting with a Resource Graph table.
|
||||
required: true
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def azure_query_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
query = str(arguments.get("query") or "").strip()
|
||||
if not query or len(query) > 4000:
|
||||
return _refuse("invalid_argument", "query is required, up to 4000 characters")
|
||||
if query.split("|")[0].strip().lower() not in AZURE_TABLES:
|
||||
return _refuse("invalid_argument", "query must start with one of: " + ", ".join(AZURE_TABLES))
|
||||
return await _azure_page("azure_query_resources", arguments, query)
|
||||
- name: azure_get_resource_metadata
|
||||
display_name: Get resource metadata
|
||||
description: Read-only provider metadata for one resource inside the connection's scope.
|
||||
parameters:
|
||||
- name: resource_id
|
||||
type: string
|
||||
description: The full ARM resource id.
|
||||
required: true
|
||||
- name: scope_entry_id
|
||||
type: string
|
||||
description: The scope entry this answers, echoed in the reply.
|
||||
required: false
|
||||
ai_implementation: |
|
||||
async def azure_get_resource_metadata(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
resource_id = str(arguments.get("resource_id") or "")
|
||||
if not re.fullmatch(r"/subscriptions/[A-Za-z0-9\-]+(/[A-Za-z0-9._()\-]+)+", resource_id):
|
||||
return _refuse("invalid_argument", "resource_id must be a full ARM resource id")
|
||||
try:
|
||||
body = await _azure_graph(f"Resources | where id =~ '{resource_id}'", 1)
|
||||
except Exception as error:
|
||||
return _upstream_failed("azure", error)
|
||||
if not body.get("data"):
|
||||
return _refuse("outside_scope", "no such resource inside this connection's scope")
|
||||
return _one_result("azure", "azure_get_resource_metadata", arguments, body["data"][0])
|
||||
- name: azure_list_servers
|
||||
display_name: List servers
|
||||
description: List virtual machines, scale sets or managed disks.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: virtual_machines, scale_sets, disks.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def azure_list_servers(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _azure_kind("azure_list_servers", arguments, AZURE_SERVERS)
|
||||
- name: azure_list_workloads
|
||||
display_name: List workloads
|
||||
description: List App Service, Container Apps or Container Instances workloads.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: app_service, container_apps, container_instances.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def azure_list_workloads(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _azure_kind("azure_list_workloads", arguments, AZURE_WORKLOADS)
|
||||
- name: azure_list_kubernetes_clusters
|
||||
display_name: List Kubernetes clusters
|
||||
description: List AKS clusters with version, node pools and networking. Stops at the cloud control plane.
|
||||
parameters: &id003
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def azure_list_kubernetes_clusters(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _azure_kind("azure_list_kubernetes_clusters", arguments, AZURE_KUBERNETES)
|
||||
- name: azure_get_network_topology
|
||||
display_name: Get network topology
|
||||
description: List virtual networks with their subnets and peerings, or route tables, NSGs, gateways, load balancers,
|
||||
private endpoints or public IPs.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: virtual_networks, route_tables, network_security_groups, gateways, load_balancers, private_endpoints,
|
||||
public_ips.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def azure_get_network_topology(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _azure_kind("azure_get_network_topology", arguments, AZURE_NETWORK)
|
||||
- name: azure_list_data_stores
|
||||
display_name: List data stores
|
||||
description: List SQL, Cosmos DB or storage account metadata. Never rows, documents or blobs.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: sql, cosmos_db, storage_accounts.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def azure_list_data_stores(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _azure_kind("azure_list_data_stores", arguments, AZURE_DATA)
|
||||
- name: azure_list_organization_policies
|
||||
display_name: List organization policies
|
||||
description: List Azure Policy assignments, definitions, initiatives, exemptions or compliance states.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: assignments, definitions, initiatives, exemptions, compliance.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def azure_list_organization_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _azure_kind("azure_list_organization_policies", arguments, AZURE_ORG_POLICIES, "PolicyResources", "assignments")
|
||||
- name: azure_list_resource_policies
|
||||
display_name: List resource policies
|
||||
description: List Key Vault access policies (never secret values), storage network rules or resource locks. Principals
|
||||
are anonymised.
|
||||
parameters:
|
||||
- name: subscription_id
|
||||
type: string
|
||||
description: For resource_locks. Needed when the scope root is a management group.
|
||||
required: false
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: key_vault_access, storage_network_rules, resource_locks.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def azure_list_resource_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
if arguments.get("kind") == "resource_locks":
|
||||
return await _azure_locks("azure_list_resource_policies", arguments)
|
||||
return await _azure_kind("azure_list_resource_policies", arguments, AZURE_RESOURCE_POLICIES)
|
||||
- name: azure_list_recommendations
|
||||
display_name: List recommendations
|
||||
description: List Azure Advisor recommendations, each with a common Well-Architected pillar.
|
||||
parameters: *id003
|
||||
ai_implementation: |
|
||||
async def azure_list_recommendations(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
query = "AdvisorResources | where type =~ 'microsoft.advisor/recommendations' | order by id asc"
|
||||
return await _azure_page("azure_list_recommendations", arguments, query, _azure_recommendation)
|
||||
62
mcp-servers/azure-discovery/.env.example
Normal file
62
mcp-servers/azure-discovery/.env.example
Normal file
@@ -0,0 +1,62 @@
|
||||
# ============================================
|
||||
# Azure Discovery - Environment Variables
|
||||
# ============================================
|
||||
# Generated by Agent Builder Platform
|
||||
#
|
||||
# SETUP INSTRUCTIONS:
|
||||
# 1. Copy this file to .env: cp .env.example .env
|
||||
# 2. Generate a secure API key: openssl rand -hex 32
|
||||
# 3. Update MCP_REGISTRATION_API_KEY with the generated key
|
||||
# 4. Build the image from the Dockerfile and run it where the MCP Gateway
|
||||
# can reach it (see README.md)
|
||||
#
|
||||
# MCP GATEWAY INTEGRATION:
|
||||
# When registering with the MCP Gateway, use the URL the Gateway reaches this
|
||||
# server at; for a container on the Gateway's network, its container name:
|
||||
# http://azure-discovery:8111
|
||||
# ============================================
|
||||
|
||||
# Server Identity
|
||||
MCP_SERVER_NAME=Azure Discovery
|
||||
MCP_SERVER_ID=azure-discovery
|
||||
MCP_SERVER_VERSION=0.1.2
|
||||
|
||||
# Server Configuration
|
||||
MCP_SERVER_PORT=8111
|
||||
|
||||
# Logging: level (DEBUG, INFO, WARNING, ERROR) and format
|
||||
# (json = one object per line, for log stores; console = for reading by eye)
|
||||
LOG_LEVEL=INFO
|
||||
LOG_FORMAT=json
|
||||
|
||||
# ============================================
|
||||
# AUTHENTICATION (REQUIRED for production!)
|
||||
# ============================================
|
||||
# This key authenticates MCP Gateway requests to this server.
|
||||
# The Gateway stores this key and includes it in all tool/call requests.
|
||||
#
|
||||
# Generate a secure key:
|
||||
# openssl rand -hex 32
|
||||
#
|
||||
# IMPORTANT: Keep this key secret! It's stored in:
|
||||
# - This .env file (gitignored)
|
||||
# - MCP Gateway database (encrypted)
|
||||
MCP_REGISTRATION_API_KEY=<generate one: openssl rand -hex 32>
|
||||
|
||||
# Set to "false" ONLY for local development/testing
|
||||
# WARNING: Disabling auth in production is a security risk!
|
||||
REQUIRE_AUTH=true
|
||||
|
||||
# ============================================
|
||||
# CREDENTIALS FOR THE UPSTREAM (sent with each request, not set here)
|
||||
# ============================================
|
||||
# The MCP Gateway sends the tenant's credential with each call, from the Vault Service.
|
||||
# true: a call without one is refused. Set to false only for local runs, where the
|
||||
# server may use its own environment.
|
||||
REQUIRE_VAULT_CONNECTION=true
|
||||
|
||||
# ============================================
|
||||
# Add your own settings below
|
||||
# ============================================
|
||||
# Credentials for the upstream are not set here: the gateway sends them with each request.
|
||||
# EXAMPLE_SETTING=value
|
||||
15
mcp-servers/azure-discovery/.gitignore
vendored
Normal file
15
mcp-servers/azure-discovery/.gitignore
vendored
Normal file
@@ -0,0 +1,15 @@
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
.venv/
|
||||
venv/
|
||||
.pytest_cache/
|
||||
|
||||
# Editors
|
||||
.vscode/
|
||||
.idea/
|
||||
47
mcp-servers/azure-discovery/Dockerfile
Normal file
47
mcp-servers/azure-discovery/Dockerfile
Normal file
@@ -0,0 +1,47 @@
|
||||
# MCP Server Dockerfile
|
||||
# Generated by Agent Builder Platform (template 1.1.0)
|
||||
#
|
||||
# Built on the platform's MCP server base image: Chainguard Python with the
|
||||
# packages in requirements.txt already installed, a non-root user (1000) and
|
||||
# no pip. This image adds only the server's own files.
|
||||
#
|
||||
# docker build -t <server>:<version> .
|
||||
# docker build --build-arg BASE_IMAGE=<local base image> -t ... .
|
||||
ARG BASE_IMAGE=kyndryl.jfrog.io/kc-ai-agent-factory-docker-local/mcp-server-base:1.1.0
|
||||
|
||||
# Stage 1: the server's extra Python packages, if requirements.txt lists any.
|
||||
# The base image's build image (<base image>-build: the base image plus uv) installs
|
||||
# them with its vendor-install script: only the packages added go on to
|
||||
# /vendor, and one that would change a package the base image already has stops
|
||||
# the build. uv never reaches the server's image.
|
||||
FROM ${BASE_IMAGE}-build AS vendor
|
||||
COPY requirements.txt constraints.txt /tmp/
|
||||
RUN vendor-install /tmp/requirements.txt /vendor /tmp/constraints.txt
|
||||
|
||||
# Stage 2: the server: the base image, its extra packages and its files.
|
||||
FROM ${BASE_IMAGE}
|
||||
|
||||
LABEL maintainer="Agent Builder Platform"
|
||||
LABEL description="Read-only discovery of a customer's Azure estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Advisor findings - through Azure Resource Graph."
|
||||
LABEL version="0.1.2"
|
||||
LABEL server.id="azure-discovery"
|
||||
LABEL template.version="1.1.0"
|
||||
|
||||
COPY --from=vendor /vendor /app/vendor/
|
||||
COPY server.py mcp_connection.py /app/
|
||||
|
||||
# Environment
|
||||
# The ConfigMap's SERVER_PORT overrides this, so the container, Service and probes agree
|
||||
ENV SERVER_PORT=8111
|
||||
ENV LOG_LEVEL=INFO
|
||||
ENV LOG_FORMAT=json
|
||||
|
||||
# Expose port
|
||||
EXPOSE 8111
|
||||
|
||||
# Health check
|
||||
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
||||
CMD python -c "import os, urllib.request; urllib.request.urlopen('http://localhost:%s/health' % (os.getenv('MCP_SERVER_PORT') or os.getenv('SERVER_PORT') or '8111'))" || exit 1
|
||||
|
||||
# Run the server
|
||||
CMD ["python", "server.py"]
|
||||
202
mcp-servers/azure-discovery/README.md
Normal file
202
mcp-servers/azure-discovery/README.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# Azure Discovery
|
||||
|
||||
Read-only discovery of a customer's Azure estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Advisor findings - through Azure Resource Graph.
|
||||
|
||||
**Version:** 0.1.2
|
||||
**Server ID:** azure-discovery
|
||||
**Port:** 8111
|
||||
|
||||
---
|
||||
|
||||
## 🚀 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>:8111`.
|
||||
|
||||
### 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
|
||||
|
||||
- **azure_check_connection**: Test the stored connection: sign in and read the scope root. Returns no customer data.
|
||||
- **azure_list_accounts**: List the estate structure: management groups, subscriptions and resource groups.
|
||||
- **azure_list_resources**: List every resource in scope, or one resource type, with id, type, location and tags.
|
||||
- **azure_query_resources**: Run a read-only Azure Resource Graph KQL query over the connection's scope. Secrets and people are removed from the results.
|
||||
- **azure_get_resource_metadata**: Read-only provider metadata for one resource inside the connection's scope.
|
||||
- **azure_list_servers**: List virtual machines, scale sets or managed disks.
|
||||
- **azure_list_workloads**: List App Service, Container Apps or Container Instances workloads.
|
||||
- **azure_list_kubernetes_clusters**: List AKS clusters with version, node pools and networking. Stops at the cloud control plane.
|
||||
- **azure_get_network_topology**: List virtual networks with their subnets and peerings, or route tables, NSGs, gateways, load balancers, private endpoints or public IPs.
|
||||
- **azure_list_data_stores**: List SQL, Cosmos DB or storage account metadata. Never rows, documents or blobs.
|
||||
- **azure_list_organization_policies**: List Azure Policy assignments, definitions, initiatives, exemptions or compliance states.
|
||||
- **azure_list_resource_policies**: List Key Vault access policies (never secret values), storage network rules or resource locks. Principals are anonymised.
|
||||
- **azure_list_recommendations**: List Azure Advisor recommendations, each with a common Well-Architected pillar.
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Authentication
|
||||
|
||||
This server uses Bearer token authentication for MCP protocol messages.
|
||||
|
||||
```bash
|
||||
# Test with authentication
|
||||
curl -X POST http://localhost:8111/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:8111`)
|
||||
- **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 |
|
||||
|---|---|---|
|
||||
| `tenant_id` | no | no |
|
||||
| `client_id` | no | no |
|
||||
| `client_secret` | no | yes |
|
||||
| `access_token` | no | yes |
|
||||
| `scope_root` | yes | no |
|
||||
| `cloud` | no | no |
|
||||
|
||||
- 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:8111 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 `azure-discovery/`, then add it to
|
||||
`mcp_servers_to_deploy.yaml` in that repository with the instances it should
|
||||
run on:
|
||||
|
||||
```yaml
|
||||
- name: "azure-discovery"
|
||||
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:8111/health
|
||||
|
||||
# List tools
|
||||
curl -X POST http://localhost:8111/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)
|
||||
29
mcp-servers/azure-discovery/constraints.txt
Normal file
29
mcp-servers/azure-discovery/constraints.txt
Normal file
@@ -0,0 +1,29 @@
|
||||
# Every package installed in a generated MCP server, pinned to one exact version:
|
||||
# the ones requirements.txt names and everything they bring in. They are
|
||||
# installed in the MCP server base image (Dockerfile.base), so every server
|
||||
# built from this template gets the same versions as the platform's own
|
||||
# services.
|
||||
annotated-doc==0.0.5
|
||||
annotated-types==0.8.0
|
||||
anyio==4.15.1
|
||||
certifi==2026.10.19
|
||||
click==8.5.0
|
||||
fastapi==0.143.2
|
||||
h11==0.16.0
|
||||
httpcore==1.0.9
|
||||
httptools==0.9.0
|
||||
httpx==0.28.1
|
||||
idna==3.20
|
||||
opentelemetry-api==1.45.1
|
||||
pydantic==2.14.1
|
||||
pydantic-core==2.50.1
|
||||
python-dotenv==1.2.4
|
||||
pyyaml==6.0.3
|
||||
starlette==1.8.0
|
||||
structlog==26.1.0
|
||||
typing-extensions==4.16.0
|
||||
typing-inspection==0.4.4
|
||||
uvicorn==0.54.0
|
||||
uvloop==0.23.0
|
||||
watchfiles==1.3.0
|
||||
websockets==16.1.1
|
||||
25
mcp-servers/azure-discovery/kubernetes/configmap.yaml
Normal file
25
mcp-servers/azure-discovery/kubernetes/configmap.yaml
Normal file
@@ -0,0 +1,25 @@
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>-config # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
data:
|
||||
|
||||
# Read by the CI/CD pipeline: the server's name, and the port it listens on
|
||||
# (used for the container, the Service and the probes)
|
||||
MCP_SERVER_NAME: "azure-discovery"
|
||||
SERVER_PORT: "8111"
|
||||
|
||||
# One JSON object per line; LOG_FORMAT=console prints readable lines
|
||||
LOG_LEVEL: "INFO"
|
||||
LOG_FORMAT: "json"
|
||||
|
||||
# Leave on. The Gateway authenticates to this server with a bearer token, and
|
||||
# turning this off makes every tool callable by anything that can reach the
|
||||
# pod inside the cluster.
|
||||
REQUIRE_AUTH: "true"
|
||||
|
||||
# Refuse a call that arrives without the tenant's credential from the Vault Service
|
||||
REQUIRE_VAULT_CONNECTION: "true"
|
||||
|
||||
# Add your own settings here
|
||||
# EXAMPLE_SETTING: "value"
|
||||
71
mcp-servers/azure-discovery/kubernetes/deployment.yaml
Normal file
71
mcp-servers/azure-discovery/kubernetes/deployment.yaml
Normal file
@@ -0,0 +1,71 @@
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
imagePullSecrets:
|
||||
- name: jfrog-secret
|
||||
containers:
|
||||
- name: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
image: <placeholder_for_image> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
imagePullPolicy: Always
|
||||
ports:
|
||||
- containerPort: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
name: http
|
||||
# Load all environment variables from ConfigMap
|
||||
envFrom:
|
||||
- secretRef:
|
||||
name: <placeholder_for_mcp_server_name>-secrets # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
optional: true # Won't fail if secret doesn't exist
|
||||
- secretRef:
|
||||
name: <placeholder_for_mcp_server_name>-dotenv-secrets # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
optional: true # Won't fail if secret doesn't exist
|
||||
- configMapRef:
|
||||
name: <placeholder_for_mcp_server_name>-config # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
# The registration key and server id are generated by the CI/CD pipeline;
|
||||
# the server needs the key to accept the Gateway's calls
|
||||
env:
|
||||
- name: MCP_REGISTRATION_API_KEY
|
||||
value: "<placeholder_for_registration_api_key>" # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
- name: MCP_SERVER_ID
|
||||
value: "<placeholder_for_server_id>" # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
resources:
|
||||
requests:
|
||||
memory: "128Mi"
|
||||
cpu: "10m"
|
||||
limits:
|
||||
memory: "1024Mi"
|
||||
cpu: "1000m"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
initialDelaySeconds: 30 # Wait X seconds before first check
|
||||
periodSeconds: 15 # Check every X seconds
|
||||
timeoutSeconds: 10 # Each check can take up to X seconds to respond
|
||||
failureThreshold: 5 # Allow X consecutive failures before marking unhealthy
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
initialDelaySeconds: 30 # Wait X seconds before first check
|
||||
periodSeconds: 15 # Check every X seconds
|
||||
timeoutSeconds: 10 # Each check can take up to X seconds to respond
|
||||
failureThreshold: 5 # Allow X consecutive failures before marking unhealthy
|
||||
|
||||
# volumes:
|
||||
# - name: execution-storage
|
||||
# persistentVolumeClaim:
|
||||
# claimName: execution-storage-pvc # Same PVC name as core-components
|
||||
20
mcp-servers/azure-discovery/kubernetes/kustomization.yaml
Normal file
20
mcp-servers/azure-discovery/kubernetes/kustomization.yaml
Normal file
@@ -0,0 +1,20 @@
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- namespace.yaml
|
||||
- deployment.yaml
|
||||
- service.yaml
|
||||
- configmap.yaml
|
||||
- secretnames.yaml
|
||||
|
||||
# Optionally add common labels
|
||||
|
||||
# Namespace for all resources
|
||||
namespace: mcp-servers
|
||||
labels:
|
||||
- includeSelectors: true
|
||||
pairs:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
environment: production
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
7
mcp-servers/azure-discovery/kubernetes/namespace.yaml
Normal file
7
mcp-servers/azure-discovery/kubernetes/namespace.yaml
Normal file
@@ -0,0 +1,7 @@
|
||||
# Do not modify this file, otherwise CI/CD pipeline will fail
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: mcp-servers
|
||||
labels:
|
||||
name: mcp-servers
|
||||
18
mcp-servers/azure-discovery/kubernetes/secretnames.yaml
Normal file
18
mcp-servers/azure-discovery/kubernetes/secretnames.yaml
Normal file
@@ -0,0 +1,18 @@
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>-secrets
|
||||
type: Opaque
|
||||
data:
|
||||
# Base64 encoded values (NOT RECOMMENDED for sensitive data)
|
||||
# To encode: echo -n 'your-secret-value' | base64
|
||||
# Example: api-key: eW91ci1hcGkta2V5LXZhbHVl
|
||||
|
||||
stringData:
|
||||
# Plain text values saved on GitHub Secrets (RECOMMENDED)
|
||||
# Example:
|
||||
#
|
||||
# DB_PASSWORD: ${DB_PASSWORD_GITHUB_SECRET}
|
||||
# ANOTHER_SECRET: ${ANOTHER_GITHUB_SECRET}
|
||||
#
|
||||
# ${DB_PASSWORD_GITHUB_SECRET} and ${ANOTHER_GITHUB_SECRET} must exist as GitHub Secrets
|
||||
33
mcp-servers/azure-discovery/kubernetes/service.yaml
Normal file
33
mcp-servers/azure-discovery/kubernetes/service.yaml
Normal file
@@ -0,0 +1,33 @@
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name>
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
type: ClusterIP
|
||||
ports:
|
||||
- port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
targetPort: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
protocol: TCP
|
||||
name: http
|
||||
selector:
|
||||
app: <placeholder_for_mcp_server_name>
|
||||
---
|
||||
# Optional: LoadBalancer service for external access
|
||||
# apiVersion: v1
|
||||
# kind: Service
|
||||
# metadata:
|
||||
# name: <placeholder_for_mcp_server_name>-external
|
||||
# labels:
|
||||
# app: <placeholder_for_mcp_server_name>
|
||||
# spec:
|
||||
# type: LoadBalancer
|
||||
# ports:
|
||||
# - port: 80
|
||||
# targetPort: 8080
|
||||
# protocol: TCP
|
||||
# name: http
|
||||
# selector:
|
||||
# app: <placeholder_for_mcp_server_name>
|
||||
256
mcp-servers/azure-discovery/mcp_connection.py
Normal file
256
mcp-servers/azure-discovery/mcp_connection.py
Normal file
@@ -0,0 +1,256 @@
|
||||
"""The connection a request carries: which upstream account this call is for.
|
||||
|
||||
An MCP server that talks to a third-party system needs that system's address and credentials. Taking
|
||||
them from environment variables makes one process serve one account for ever. Here the MCP Gateway
|
||||
sends them with each call, from the Vault Service, in MCP's own `_meta` field, under our vendor prefix:
|
||||
|
||||
initialize result _meta["com.kyndryl.mcp/connection-schema"] what this server needs (JSON Schema)
|
||||
_meta["com.kyndryl.mcp/verify-tool"] the tool that tests a connection
|
||||
tools/call, resources/read, prompts/get
|
||||
params._meta["com.kyndryl.mcp/connection"] the values, matching that schema
|
||||
|
||||
`_meta` is where the specification tells implementations to put their own data, so a client that does
|
||||
not know these keys ignores them. The values never travel in `arguments`, which is what the model
|
||||
writes and reads, so a credential cannot enter the model's context.
|
||||
|
||||
The connection is bound for the life of one request and read with `active()`. It is None when the caller
|
||||
sent nothing; whether the server may then use its own environment is decided in server.py
|
||||
(REQUIRE_VAULT_CONNECTION, which is on by default).
|
||||
|
||||
WHAT IS STANDARD AND WHAT IS OURS
|
||||
---------------------------------
|
||||
The mechanism is standard. `_meta` is the specification's sanctioned place for implementation-specific
|
||||
data, with formal key-naming rules (2026-07-28, "General fields / _meta"):
|
||||
|
||||
Prefix ... SHOULD use reverse DNS notation. Any prefix where the second label is
|
||||
`modelcontextprotocol` or `mcp` is reserved for MCP use ... third-party extensions use their own
|
||||
vendor prefix.
|
||||
|
||||
`com.kyndryl.mcp/` satisfies that: the second label is `kyndryl`, so it is a legitimate vendor prefix and
|
||||
not reserved. A client that does not recognise our keys ignores them, which is exactly what `_meta` is for.
|
||||
The value carried is a *separate* upstream credential, never the caller's own token (the specification
|
||||
says a server MUST NOT pass through the token it received from its client).
|
||||
|
||||
Only the three key names and the shape of their payloads are ours. When SEP-2127 (MCP Server Card) lands,
|
||||
the schema is what moves onto the card, and the key names are the only thing that changes.
|
||||
|
||||
The third key, VERIFY_TOOL_KEY, adds very little. Checking a credential is a plain `tools/call` against an
|
||||
ordinary tool that appears in `tools/list` like any other: no new method, no new transport. The only
|
||||
question that needed answering is WHICH tool, and the alternative was for the gateway to guess by name. A
|
||||
server that advertises nothing here is simply not verifiable.
|
||||
|
||||
STATELESSNESS
|
||||
-------------
|
||||
The 2026-07-28 specification made MCP explicitly stateless: "Servers MUST NOT rely on prior requests over
|
||||
the same connection to establish context ... Every request supplies this metadata in its _meta field."
|
||||
A module-level connection built once at import is exactly the state the specification tells servers not to
|
||||
keep. Binding the connection per request is therefore not only what multi-tenancy needs, it is what the
|
||||
protocol asks for.
|
||||
|
||||
HOW IT IS USED (server.py does all of this; a tool only calls get_connection())
|
||||
------------------------------------------------------------------------------
|
||||
import mcp_connection
|
||||
|
||||
# advertise, in the initialize result
|
||||
result["_meta"] = mcp_connection.schema_meta(CONNECTION_SCHEMA, verify_tool="verify_connection")
|
||||
|
||||
# bind, for the life of one request
|
||||
token = mcp_connection.bind(mcp_connection.from_params(request.params))
|
||||
try:
|
||||
... # mcp_connection.active() anywhere below
|
||||
finally:
|
||||
mcp_connection.unbind(token)
|
||||
|
||||
LOGS AND ERROR MESSAGES
|
||||
-----------------------
|
||||
`scrub()` is applied to every log line, and to the `error` text of a failed tool call, so the connection's
|
||||
values and credential-looking URL parameters (`?key=...`) never leave the process. `redact()` does the
|
||||
connection values alone. Neither is applied to a successful result: a presigned URL a tool returns on
|
||||
purpose must survive.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextvars
|
||||
import hashlib
|
||||
import hmac
|
||||
import json
|
||||
import re
|
||||
import secrets
|
||||
from typing import Any, Callable, Dict, List, Optional
|
||||
|
||||
VENDOR = "com.kyndryl.mcp"
|
||||
SCHEMA_KEY = f"{VENDOR}/connection-schema"
|
||||
CONNECTION_KEY = f"{VENDOR}/connection"
|
||||
VERIFY_TOOL_KEY = f"{VENDOR}/verify-tool"
|
||||
|
||||
_active: contextvars.ContextVar[Optional[Dict[str, Any]]] = contextvars.ContextVar(
|
||||
"mcp_connection", default=None
|
||||
)
|
||||
|
||||
# Per process, so a fingerprint in a log cannot be checked against a guessed credential offline
|
||||
_FINGERPRINT_KEY = secrets.token_bytes(32)
|
||||
|
||||
|
||||
def schema_meta(schema: Dict[str, Any], verify_tool: Optional[str] = None) -> Dict[str, Any]:
|
||||
"""The `_meta` object that advertises `schema` on an initialize result."""
|
||||
meta: Dict[str, Any] = {SCHEMA_KEY: schema}
|
||||
if verify_tool:
|
||||
meta[VERIFY_TOOL_KEY] = verify_tool
|
||||
return meta
|
||||
|
||||
|
||||
def verify_tool_from_initialize(result: Optional[Dict[str, Any]]) -> Optional[str]:
|
||||
"""The verify tool an initialize result advertises, or None.
|
||||
|
||||
The reader half of schema_meta, here rather than in the gateway so the two ends of the key cannot
|
||||
drift apart.
|
||||
"""
|
||||
if not isinstance(result, dict):
|
||||
return None
|
||||
meta = result.get("_meta")
|
||||
if not isinstance(meta, dict):
|
||||
return None
|
||||
name = meta.get(VERIFY_TOOL_KEY)
|
||||
return name if isinstance(name, str) and name.strip() else None
|
||||
|
||||
|
||||
def from_params(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
|
||||
"""The connection in a request's `params._meta`, or None.
|
||||
|
||||
Anything that is not an object counts as absent: a malformed connection must not be more
|
||||
powerful than none at all.
|
||||
"""
|
||||
if not isinstance(params, dict):
|
||||
return None
|
||||
meta = params.get("_meta")
|
||||
if not isinstance(meta, dict):
|
||||
return None
|
||||
profile = meta.get(CONNECTION_KEY)
|
||||
return profile if isinstance(profile, dict) and profile else None
|
||||
|
||||
|
||||
def bind(profile: Optional[Dict[str, Any]]) -> contextvars.Token:
|
||||
"""Make `profile` the connection for this request."""
|
||||
return _active.set(profile)
|
||||
|
||||
|
||||
def unbind(token: contextvars.Token) -> None:
|
||||
try:
|
||||
_active.reset(token)
|
||||
except ValueError:
|
||||
_active.set(None)
|
||||
|
||||
|
||||
def active() -> Optional[Dict[str, Any]]:
|
||||
"""The connection for this request, or None."""
|
||||
return _active.get()
|
||||
|
||||
|
||||
def fingerprint(profile: Optional[Dict[str, Any]]) -> str:
|
||||
"""A short id for a connection, safe to log and to cache on; the credential never is the key."""
|
||||
if not profile:
|
||||
return "env"
|
||||
canonical = json.dumps(profile, sort_keys=True, separators=(",", ":"), default=str)
|
||||
return hmac.new(_FINGERPRINT_KEY, canonical.encode("utf-8"), hashlib.sha256).hexdigest()[:16]
|
||||
|
||||
|
||||
def redact(text: Any) -> str:
|
||||
"""`text` with every value of this request's connection replaced, for logs and error replies.
|
||||
|
||||
A tool can put a credential in an exception message without meaning to. Values shorter than four
|
||||
characters are left alone: replacing them would garble ordinary text.
|
||||
"""
|
||||
result = str(text)
|
||||
values = [v for v in (active() or {}).values() if isinstance(v, str) and len(v) >= 4]
|
||||
for value in sorted(values, key=len, reverse=True):
|
||||
result = result.replace(value, "[redacted]")
|
||||
return result
|
||||
|
||||
|
||||
# Query parameters that carry a credential in the URL of an upstream request
|
||||
_URL_CREDENTIAL = re.compile(
|
||||
r"([?&;](?:api[_-]?key|apikey|key|token|access[_-]?token|auth|secret|password|passwd|"
|
||||
r"client[_-]?secret|appid|app[_-]?id|sig|signature)=)[^&\s\"'#<>]+",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
|
||||
def scrub(value: Any, _depth: int = 0) -> Any:
|
||||
"""`value` with credentials taken out, for anything that is logged or sent back to a caller.
|
||||
|
||||
Strings lose the request's connection values and the value of any credential query parameter in a
|
||||
URL (`?key=...`); dicts, lists and tuples are scrubbed inside. Anything else is returned as it is.
|
||||
Not for tool results in general: a presigned URL a tool returns on purpose would be damaged.
|
||||
"""
|
||||
if isinstance(value, str):
|
||||
return _URL_CREDENTIAL.sub(r"\1[redacted]", redact(value))
|
||||
if _depth > 5:
|
||||
return value
|
||||
if isinstance(value, dict):
|
||||
return {k: scrub(v, _depth + 1) for k, v in value.items()}
|
||||
if isinstance(value, (list, tuple)):
|
||||
return type(value)(scrub(v, _depth + 1) for v in value)
|
||||
return value
|
||||
|
||||
|
||||
def missing_fields(profile: Optional[Dict[str, Any]], schema: Dict[str, Any]) -> List[str]:
|
||||
"""The required fields of `schema` that `profile` does not supply."""
|
||||
if not profile:
|
||||
return []
|
||||
required = schema.get("required") or []
|
||||
return [name for name in required if not str(profile.get(name) or "").strip()]
|
||||
|
||||
|
||||
def install_invalid_request_handler(app: Any, on_invalid: Optional[Callable[[str], None]] = None) -> None:
|
||||
"""Answer a request that is not valid JSON-RPC with a JSON-RPC error that does not repeat the request.
|
||||
|
||||
FastAPI's own answer (HTTP 422) repeats the request body under "input". The body is where the gateway puts
|
||||
the tenant's connection, so a request that is merely malformed (no "id", say) would get the credential back
|
||||
in the reply, and in the log of anything that records replies. The status stays 422; the body is a JSON-RPC
|
||||
error (-32600) that names only the fields at fault. `on_invalid`, if given, is called with that text, already
|
||||
reduced to harmless characters, so the caller can log it in its own style.
|
||||
|
||||
Call it once, right after `app = FastAPI(...)`. FastAPI is imported here, not at module level, so the rest of
|
||||
this module stays importable without it.
|
||||
"""
|
||||
from fastapi.exceptions import RequestValidationError
|
||||
from fastapi.responses import JSONResponse
|
||||
|
||||
@app.exception_handler(RequestValidationError)
|
||||
async def invalid_request(request, exc):
|
||||
names = {
|
||||
"body" if error.get("type") == "json_invalid" else ".".join(str(p) for p in error.get("loc", ())[1:]) or "body"
|
||||
for error in exc.errors()
|
||||
}
|
||||
fields = re.sub(r"[^\w.\-, ]", "?", ", ".join(sorted(names)))[:200]
|
||||
if on_invalid is not None:
|
||||
on_invalid(fields)
|
||||
return JSONResponse(
|
||||
status_code=422,
|
||||
content={
|
||||
"jsonrpc": "2.0",
|
||||
"id": None,
|
||||
"result": None,
|
||||
"error": {"code": -32600, "message": "Invalid request: check " + fields},
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"install_invalid_request_handler",
|
||||
"VENDOR",
|
||||
"SCHEMA_KEY",
|
||||
"CONNECTION_KEY",
|
||||
"VERIFY_TOOL_KEY",
|
||||
"schema_meta",
|
||||
"verify_tool_from_initialize",
|
||||
"from_params",
|
||||
"bind",
|
||||
"unbind",
|
||||
"active",
|
||||
"fingerprint",
|
||||
"redact",
|
||||
"scrub",
|
||||
"missing_fields",
|
||||
]
|
||||
39
mcp-servers/azure-discovery/requirements.txt
Normal file
39
mcp-servers/azure-discovery/requirements.txt
Normal file
@@ -0,0 +1,39 @@
|
||||
# MCP Server Dependencies
|
||||
# Generated by Agent Builder Platform
|
||||
|
||||
# Each dependency is pinned to one exact version, and constraints.txt pins everything they bring
|
||||
# in, so two builds of the same server get the same packages -- the same versions as the
|
||||
# platform's own services. The packages below are already installed in the MCP server base
|
||||
# image the Dockerfile builds on; a package added to this file is installed on top of them at
|
||||
# build time. Changing the version of one the base has stops the build: the base image moves
|
||||
# those, with the template.
|
||||
|
||||
# Core Framework
|
||||
# FastAPI - Modern web framework for MCP server
|
||||
fastapi==0.143.2
|
||||
|
||||
# ASGI Server
|
||||
# Uvicorn - Lightning-fast ASGI server
|
||||
uvicorn[standard]==0.54.0
|
||||
|
||||
# Data Validation
|
||||
# Pydantic - Data validation using Python type hints
|
||||
pydantic==2.14.1
|
||||
|
||||
# HTTP Client
|
||||
# HTTPX - Async HTTP client for API calls
|
||||
httpx==0.28.1
|
||||
|
||||
# Environment Variables
|
||||
# python-dotenv - Load environment from .env files
|
||||
python-dotenv==1.2.4
|
||||
|
||||
# Structured Logging
|
||||
# structlog - JSON log lines (see LOG_FORMAT in server.py)
|
||||
structlog==26.1.0
|
||||
|
||||
# Optional: Add your custom dependencies below
|
||||
# requests>=2.31.0
|
||||
# aiofiles>=23.2.1
|
||||
# sqlalchemy>=2.0.0
|
||||
# redis>=5.0.0
|
||||
1333
mcp-servers/azure-discovery/server.py
Normal file
1333
mcp-servers/azure-discovery/server.py
Normal file
File diff suppressed because it is too large
Load Diff
223
mcp-servers/azure-discovery/tests/test_azure.py
Normal file
223
mcp-servers/azure-discovery/tests/test_azure.py
Normal file
@@ -0,0 +1,223 @@
|
||||
import asyncio
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
||||
import mcp_connection # noqa: E402
|
||||
import server # noqa: E402
|
||||
|
||||
CONNECTION = {"tenant_id": "tenant-1", "client_id": "client", "client_secret": "s3cret",
|
||||
"scope_root": "managementGroups/mg-root"}
|
||||
|
||||
|
||||
class Azure:
|
||||
def __init__(self, rows=None, skip=None, status=200):
|
||||
self.rows, self.skip, self.status, self.queries = rows or [], skip, status, []
|
||||
|
||||
def __call__(self, request):
|
||||
if "login.microsoftonline.com" in str(request.url):
|
||||
assert b"client_secret=s3cret" in request.content
|
||||
return httpx.Response(200, json={"access_token": "tok", "expires_in": 3600})
|
||||
assert request.headers["Authorization"] == "Bearer tok"
|
||||
assert "Microsoft.ResourceGraph" in str(request.url)
|
||||
self.queries.append(json.loads(request.content))
|
||||
if self.status != 200:
|
||||
return httpx.Response(self.status, json={"error": "said too much about ana@customer.example"})
|
||||
body = {"data": self.rows, "count": len(self.rows)}
|
||||
if self.skip:
|
||||
body["$skipToken"] = self.skip
|
||||
return httpx.Response(200, json=body)
|
||||
|
||||
|
||||
def call(tool, arguments, azure, connection=CONNECTION):
|
||||
server.AZURE_TOKENS.clear()
|
||||
|
||||
async def run():
|
||||
client = httpx.AsyncClient(transport=httpx.MockTransport(azure))
|
||||
original = server.get_upstream_client
|
||||
server.get_upstream_client = lambda kind, build: client
|
||||
bound = mcp_connection.bind(connection)
|
||||
try:
|
||||
return await getattr(server, tool)(arguments)
|
||||
finally:
|
||||
mcp_connection.unbind(bound)
|
||||
server.get_upstream_client = original
|
||||
await client.aclose()
|
||||
|
||||
return asyncio.run(run())
|
||||
|
||||
|
||||
def test_every_query_is_scoped_by_the_connection():
|
||||
azure = Azure([{"id": "/subscriptions/1/x"}])
|
||||
result = call("azure_list_servers", {}, azure)
|
||||
assert result["success"]
|
||||
assert azure.queries[0]["managementGroups"] == ["mg-root"]
|
||||
assert "microsoft.compute/virtualmachines" in azure.queries[0]["query"]
|
||||
|
||||
|
||||
def test_a_caller_cannot_widen_the_scope():
|
||||
azure = Azure([])
|
||||
call("azure_query_resources", {"query": "Resources | limit 1", "managementGroups": ["other"]}, azure)
|
||||
assert azure.queries[0]["managementGroups"] == ["mg-root"]
|
||||
|
||||
|
||||
def test_query_must_start_with_a_known_table():
|
||||
azure = Azure([])
|
||||
result = call("azure_query_resources", {"query": "securityresources | limit 1"}, azure)
|
||||
assert result["error"]["code"] == "invalid_argument" and not azure.queries
|
||||
|
||||
|
||||
def test_resource_outside_scope_is_refused():
|
||||
result = call("azure_get_resource_metadata", {"resource_id": "/subscriptions/other/resourceGroups/rg/x/y"}, Azure([]))
|
||||
assert result["error"]["code"] == "outside_scope"
|
||||
|
||||
|
||||
def test_resource_id_cannot_inject_kql():
|
||||
azure = Azure([])
|
||||
result = call("azure_get_resource_metadata", {"resource_id": "/subscriptions/1' or 1==1 //"}, azure)
|
||||
assert result["error"]["code"] == "invalid_argument" and not azure.queries
|
||||
|
||||
|
||||
def test_resource_type_cannot_inject_kql():
|
||||
azure = Azure([])
|
||||
result = call("azure_list_resources", {"resource_type": "x' or 1==1 //"}, azure)
|
||||
assert result["error"]["code"] == "invalid_argument" and not azure.queries
|
||||
|
||||
|
||||
def test_vm_secrets_and_owner_are_removed():
|
||||
vm = {"id": "/subscriptions/1/vm", "tags": {"owner": "Ana"},
|
||||
"properties": {"osProfile": {"customData": "c2VjcmV0", "adminUsername": "azureuser"}}}
|
||||
text = json.dumps(call("azure_list_servers", {}, Azure([vm])))
|
||||
assert "c2VjcmV0" not in text and '"Ana"' not in text
|
||||
|
||||
|
||||
def test_key_vault_principals_are_anonymised():
|
||||
vault = {"id": "/v", "properties": {"accessPolicies": [{"objectId": "person-guid", "permissions": {"secrets": ["get"]}}]}}
|
||||
text = json.dumps(call("azure_list_resource_policies", {"kind": "key_vault_access"}, Azure([vault])))
|
||||
assert "person-guid" not in text and '"get"' in text
|
||||
|
||||
|
||||
def test_paging_passes_the_skip_token():
|
||||
azure = Azure([{"id": "a"}], skip="more")
|
||||
first = call("azure_list_servers", {}, azure)["data"]
|
||||
call("azure_list_servers", {"page_token": first["next_page_token"]}, azure)
|
||||
assert azure.queries[1]["options"]["$skipToken"] == "more"
|
||||
|
||||
|
||||
def test_advisor_categories_map_to_pillars():
|
||||
row = {"id": "r", "properties": {"category": "HighAvailability"}}
|
||||
item = call("azure_list_recommendations", {}, Azure([row]))["data"]["items"][0]
|
||||
assert item["pillar"] == "reliability" and item["provider_category"] == "HighAvailability"
|
||||
|
||||
|
||||
def test_upstream_error_text_is_not_returned():
|
||||
text = json.dumps(call("azure_list_servers", {}, Azure(status=403)))
|
||||
assert "403" in text and "ana@" not in text
|
||||
|
||||
|
||||
def test_check_connection_reports_failure():
|
||||
assert call("azure_check_connection", {}, Azure(status=401))["ok"] is False
|
||||
assert call("azure_check_connection", {}, Azure([]))["ok"] is True
|
||||
|
||||
|
||||
@pytest.mark.parametrize("scope", ["", "tenants/x", "managementGroups/a/b"])
|
||||
def test_bad_scope_root_fails_closed(scope):
|
||||
result = call("azure_list_servers", {}, Azure([]), {**CONNECTION, "scope_root": scope})
|
||||
assert result["success"] is False
|
||||
|
||||
|
||||
def test_a_stored_access_token_is_used_without_signing_in():
|
||||
def azure(request):
|
||||
assert "login.microsoftonline.com" not in str(request.url)
|
||||
assert request.headers["Authorization"] == "Bearer personal"
|
||||
return httpx.Response(200, json={"data": [{"id": "/subscriptions/1/vm"}]})
|
||||
|
||||
connection = {"access_token": "personal", "scope_root": "subscriptions/sub-1"}
|
||||
assert call("azure_list_servers", {}, azure, connection)["data"]["count"] == 1
|
||||
|
||||
|
||||
def test_an_incomplete_connection_is_refused():
|
||||
assert call("azure_list_servers", {}, Azure([]), {"scope_root": "subscriptions/sub-1"})["success"] is False
|
||||
|
||||
|
||||
def throttled_then(ok, times=1, headers=None):
|
||||
state = {"left": times}
|
||||
|
||||
def azure(request):
|
||||
if "login.microsoftonline.com" in str(request.url):
|
||||
return httpx.Response(200, json={"access_token": "tok", "expires_in": 3600})
|
||||
if state["left"]:
|
||||
state["left"] -= 1
|
||||
return httpx.Response(429, headers=headers or {"retry-after": "0"}, json={})
|
||||
return ok
|
||||
|
||||
return azure, state
|
||||
|
||||
|
||||
def test_a_throttled_call_waits_and_succeeds():
|
||||
azure, state = throttled_then(httpx.Response(200, json={"data": [{"id": "a"}]}), 2)
|
||||
assert call("azure_list_servers", {}, azure)["data"]["count"] == 1 and state["left"] == 0
|
||||
|
||||
|
||||
def test_resource_graph_quota_header_is_understood():
|
||||
azure, _ = throttled_then(httpx.Response(200, json={"data": []}), 1, {"x-ms-user-quota-resets-after": "00:00:00"})
|
||||
assert call("azure_list_servers", {}, azure)["success"] is True
|
||||
|
||||
|
||||
def test_throttling_that_never_ends_fails_cleanly():
|
||||
azure, _ = throttled_then(None, 99)
|
||||
result = call("azure_list_servers", {}, azure)
|
||||
assert result["success"] is False and "429" in result["error"]["message"]
|
||||
|
||||
|
||||
def test_a_long_requested_wait_gives_up_instead_of_hanging():
|
||||
azure, state = throttled_then(None, 99, {"retry-after": "3600"})
|
||||
assert call("azure_list_servers", {}, azure)["success"] is False
|
||||
assert state["left"] >= 90
|
||||
|
||||
|
||||
LOCK_SUB = {**CONNECTION, "scope_root": "subscriptions/sub-1"}
|
||||
|
||||
|
||||
def arm(value, urls):
|
||||
def azure(request):
|
||||
if "login.microsoftonline.com" in str(request.url):
|
||||
return httpx.Response(200, json={"access_token": "tok", "expires_in": 3600})
|
||||
urls.append(str(request.url))
|
||||
if "ResourceGraph" in str(request.url):
|
||||
return httpx.Response(200, json={"data": value})
|
||||
return httpx.Response(200, json={"value": [{"name": "do-not-delete", "properties": {"level": "CanNotDelete"}}]})
|
||||
|
||||
return azure
|
||||
|
||||
|
||||
def test_locks_come_from_arm_not_resource_graph():
|
||||
urls = []
|
||||
data = call("azure_list_resource_policies", {"kind": "resource_locks"}, arm([], urls), LOCK_SUB)["data"]
|
||||
assert data["count"] == 1 and "/subscriptions/sub-1/providers/Microsoft.Authorization/locks" in urls[0]
|
||||
|
||||
|
||||
def test_lock_subscription_outside_the_scope_is_refused():
|
||||
result = call("azure_list_resource_policies", {"kind": "resource_locks", "subscription_id": "other"}, arm([], []), LOCK_SUB)
|
||||
assert result["error"]["code"] == "outside_scope"
|
||||
|
||||
|
||||
def test_management_group_needs_a_subscription_in_scope():
|
||||
urls = []
|
||||
assert call("azure_list_resource_policies", {"kind": "resource_locks"}, arm([], urls))["error"]["code"] == "outside_scope"
|
||||
result = call("azure_list_resource_policies", {"kind": "resource_locks", "subscription_id": "sub-9"}, arm([], urls))
|
||||
assert result["error"]["code"] == "outside_scope"
|
||||
found = call("azure_list_resource_policies", {"kind": "resource_locks", "subscription_id": "sub-9"}, arm([{"id": "x"}], urls))
|
||||
assert found["data"]["count"] == 1
|
||||
|
||||
|
||||
def test_a_forged_lock_page_token_cannot_send_the_token_elsewhere():
|
||||
urls = []
|
||||
forged = server._write_page("https://attacker.example/steal", 0)
|
||||
args = {"kind": "resource_locks", "page_token": forged}
|
||||
assert call("azure_list_resource_policies", args, arm([], urls), LOCK_SUB)["error"]["code"] == "invalid_page_token"
|
||||
assert not urls
|
||||
360
mcp-servers/azure-discovery/tests/test_conformance.py
Normal file
360
mcp-servers/azure-discovery/tests/test_conformance.py
Normal file
@@ -0,0 +1,360 @@
|
||||
"""Conformance checks for an MCP server that takes its upstream credentials from the MCP Gateway.
|
||||
|
||||
Run these against a running server before you push it. They need only `pytest` and `httpx`, import
|
||||
nothing from the server and talk to it over HTTP, so they work on a server from the MCP Server
|
||||
Builder and on one written by hand.
|
||||
|
||||
pip install pytest httpx
|
||||
MCP_SERVER_URL=http://localhost:8100 MCP_REGISTRATION_API_KEY=<the server's key> pytest tests/ -v
|
||||
|
||||
What is checked, and why:
|
||||
|
||||
Protocol the server answers /health, refuses callers without its key, and speaks JSON-RPC
|
||||
correctly (initialize, tools/list, ids echoed, errors as errors).
|
||||
Connection a server that needs an upstream account says so in its initialize result
|
||||
(`_meta["com.kyndryl.mcp/connection-schema"]`) and takes the account from each
|
||||
request (`params._meta["com.kyndryl.mcp/connection"]`), not from its own environment.
|
||||
Such a server refuses a call that carries none (fail closed), reports which required
|
||||
field is missing, takes nothing from `arguments`, and never repeats a credential in a
|
||||
reply (the values of fields marked `writeOnly`; every value if none is marked). A server that needs no account skips these checks.
|
||||
|
||||
Settings (environment variables):
|
||||
|
||||
MCP_SERVER_URL default http://localhost:8100
|
||||
MCP_REGISTRATION_API_KEY the key the server was started with (required unless the
|
||||
server has authentication switched off)
|
||||
CONFORMANCE_EXPECT_FAIL_CLOSED default true. Set false only for a server you run locally
|
||||
with REQUIRE_VAULT_CONNECTION=false, so that checks which
|
||||
need a refusal are skipped rather than failed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import secrets
|
||||
import uuid
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
VENDOR = "com.kyndryl.mcp"
|
||||
SCHEMA_KEY = f"{VENDOR}/connection-schema"
|
||||
VERIFY_TOOL_KEY = f"{VENDOR}/verify-tool"
|
||||
CONNECTION_KEY = f"{VENDOR}/connection"
|
||||
|
||||
BASE_URL = os.getenv("MCP_SERVER_URL", "http://localhost:8100").rstrip("/")
|
||||
API_KEY = os.getenv("MCP_REGISTRATION_API_KEY", "")
|
||||
EXPECT_FAIL_CLOSED = os.getenv("CONFORMANCE_EXPECT_FAIL_CLOSED", "true").strip().lower() != "false"
|
||||
|
||||
# A value no server could contain by accident, so finding it in a reply means the server repeated it.
|
||||
SENTINEL = f"sentinel-{secrets.token_hex(6)}"
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ helpers
|
||||
|
||||
|
||||
def auth_headers(key: Optional[str] = None) -> Dict[str, str]:
|
||||
key = API_KEY if key is None else key
|
||||
return {"Authorization": f"Bearer {key}"} if key else {}
|
||||
|
||||
|
||||
def rpc(
|
||||
client: httpx.Client,
|
||||
method: str,
|
||||
params: Optional[Dict[str, Any]] = None,
|
||||
*,
|
||||
request_id: Any = "1",
|
||||
headers: Optional[Dict[str, str]] = None,
|
||||
) -> httpx.Response:
|
||||
return client.post(
|
||||
"/messages",
|
||||
json={"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}},
|
||||
headers=auth_headers() if headers is None else headers,
|
||||
)
|
||||
|
||||
|
||||
def result_of(client: httpx.Client, method: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
||||
response = rpc(client, method, params)
|
||||
assert response.status_code == 200, f"{method} answered HTTP {response.status_code}: {response.text[:300]}"
|
||||
body = response.json()
|
||||
assert not body.get("error"), f"{method} returned an error: {body['error']}"
|
||||
return body["result"]
|
||||
|
||||
|
||||
def with_connection(params: Dict[str, Any], connection: Optional[Dict[str, Any]]) -> Dict[str, Any]:
|
||||
if connection is None:
|
||||
return params
|
||||
return {**params, "_meta": {CONNECTION_KEY: connection}}
|
||||
|
||||
|
||||
def value_for(name: str, spec: Dict[str, Any]) -> Any:
|
||||
"""A value of the right shape for a connection field, carrying the sentinel."""
|
||||
kind = spec.get("type", "string")
|
||||
if kind == "string" and spec.get("format") == "uri":
|
||||
return f"https://{SENTINEL}.invalid"
|
||||
if kind == "integer":
|
||||
return 12345
|
||||
if kind == "boolean":
|
||||
return True
|
||||
return f"{SENTINEL}-{name}"
|
||||
|
||||
|
||||
def full_connection(schema: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return {name: value_for(name, spec) for name, spec in (schema.get("properties") or {}).items()}
|
||||
|
||||
|
||||
def secret_values(schema: Dict[str, Any]) -> List[str]:
|
||||
"""The sent values that must never come back: those of fields marked secret (`writeOnly`).
|
||||
|
||||
A tool may repeat a base URL or a region. If the server marks no field secret, every value is
|
||||
treated as one, because then nothing says which are safe to repeat.
|
||||
"""
|
||||
connection = full_connection(schema)
|
||||
properties = schema.get("properties") or {}
|
||||
marked = [n for n, spec in properties.items() if spec.get("writeOnly")]
|
||||
return [str(connection[n]) for n in (marked or list(properties))]
|
||||
|
||||
|
||||
def repeated(response: httpx.Response, schema: Dict[str, Any]) -> List[str]:
|
||||
return [v for v in secret_values(schema) if v in response.text]
|
||||
|
||||
|
||||
def _string_values(node: Any) -> List[str]:
|
||||
"""Every string anywhere in a JSON value."""
|
||||
if isinstance(node, str):
|
||||
return [node]
|
||||
if isinstance(node, dict):
|
||||
return [v for item in node.values() for v in _string_values(item)]
|
||||
if isinstance(node, list):
|
||||
return [v for item in node for v in _string_values(item)]
|
||||
return []
|
||||
|
||||
|
||||
def call(client: httpx.Client, tool: str, connection: Optional[Dict[str, Any]], arguments: Optional[Dict] = None):
|
||||
return rpc(client, "tools/call", with_connection({"name": tool, "arguments": arguments or {}}, connection))
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ fixtures
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def client():
|
||||
with httpx.Client(base_url=BASE_URL, timeout=30.0) as session:
|
||||
try:
|
||||
session.get("/health")
|
||||
except httpx.HTTPError as error:
|
||||
pytest.exit(f"Cannot reach the server at {BASE_URL}: {error}. Start it, or set MCP_SERVER_URL.", 2)
|
||||
yield session
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def initialize(client) -> Dict[str, Any]:
|
||||
return result_of(client, "initialize", {"protocolVersion": "1.0.0", "clientInfo": {"name": "conformance"}})
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def tools(client) -> List[Dict[str, Any]]:
|
||||
return result_of(client, "tools/list")["tools"]
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def schema(initialize) -> Optional[Dict[str, Any]]:
|
||||
return (initialize.get("_meta") or {}).get(SCHEMA_KEY)
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def needs_connection(schema) -> Dict[str, Any]:
|
||||
if not schema or not schema.get("properties"):
|
||||
pytest.skip("the server advertises no connection fields, so it takes no per-request credentials")
|
||||
return schema
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def probe_tool(initialize, tools) -> str:
|
||||
"""The tool to call in the connection checks: the verify tool when there is one."""
|
||||
verify = (initialize.get("_meta") or {}).get(VERIFY_TOOL_KEY)
|
||||
if verify:
|
||||
return verify
|
||||
assert tools, "the server lists no tools to call"
|
||||
return tools[0]["name"]
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ protocol
|
||||
|
||||
|
||||
def test_health_answers(client):
|
||||
assert client.get("/health").status_code == 200
|
||||
|
||||
|
||||
def test_the_public_auth_endpoint_reveals_no_key(client):
|
||||
response = client.get("/.well-known/mcp-auth")
|
||||
if response.status_code == 404:
|
||||
pytest.skip("the server has no /.well-known/mcp-auth endpoint")
|
||||
assert response.status_code == 200
|
||||
if API_KEY:
|
||||
# A value that equals the key is always a leak. A short key can also appear inside ordinary words
|
||||
# ("nc" in "auth_required"), so searching the text for it is only meaningful for a real-length key.
|
||||
assert API_KEY not in _string_values(response.json()), "/.well-known/mcp-auth returns the server's key"
|
||||
if len(API_KEY) >= 12:
|
||||
assert API_KEY not in response.text, "/.well-known/mcp-auth returns the server's key"
|
||||
|
||||
|
||||
def test_a_call_without_the_servers_key_is_refused(client):
|
||||
response = rpc(client, "tools/list", headers={})
|
||||
assert response.status_code in (401, 403), f"answered HTTP {response.status_code} to a caller with no key"
|
||||
|
||||
|
||||
def test_a_call_with_the_wrong_key_is_refused(client):
|
||||
response = rpc(client, "tools/list", headers=auth_headers("not-the-key-" + uuid.uuid4().hex))
|
||||
assert response.status_code in (401, 403), f"answered HTTP {response.status_code} to a caller with the wrong key"
|
||||
|
||||
|
||||
def test_initialize_describes_the_server(initialize):
|
||||
assert initialize["serverInfo"]["name"]
|
||||
assert isinstance(initialize.get("capabilities"), dict)
|
||||
|
||||
|
||||
def test_tools_have_a_name_a_description_and_an_object_schema(tools):
|
||||
assert isinstance(tools, list)
|
||||
names = [t["name"] for t in tools]
|
||||
assert len(names) == len(set(names)), "two tools share a name"
|
||||
for tool in tools:
|
||||
assert tool["name"] and tool.get("description"), f"tool {tool.get('name')!r} lacks a name or description"
|
||||
assert tool["inputSchema"]["type"] == "object", f"{tool['name']} has no object inputSchema"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("request_id", ["conformance-1", 7])
|
||||
def test_the_reply_echoes_the_request_id(client, request_id):
|
||||
response = rpc(client, "tools/list", request_id=request_id)
|
||||
assert response.status_code == 200
|
||||
assert response.json()["id"] == request_id
|
||||
|
||||
|
||||
def test_an_unknown_method_is_an_error_not_a_crash(client):
|
||||
response = rpc(client, "no/such/method")
|
||||
assert response.status_code == 200
|
||||
assert response.json().get("error"), "an unknown method returned no error"
|
||||
|
||||
|
||||
def test_an_unknown_tool_is_an_error_not_a_crash(client):
|
||||
response = rpc(client, "tools/call", {"name": f"no_such_tool_{uuid.uuid4().hex[:8]}", "arguments": {}})
|
||||
assert response.status_code == 200
|
||||
assert response.json().get("error"), "an unknown tool returned no error"
|
||||
|
||||
|
||||
def test_arguments_that_are_not_an_object_are_the_callers_mistake(client, tools, schema):
|
||||
params = {"name": tools[0]["name"], "arguments": ["not", "an", "object"]}
|
||||
# With a connection, when the server wants one: a refusal for lacking it would answer -32602 too
|
||||
response = rpc(client, "tools/call", with_connection(params, full_connection(schema) if schema else None))
|
||||
assert response.status_code == 200
|
||||
error = response.json().get("error")
|
||||
assert error and error.get("code") == -32602, f"expected invalid params (-32602), got: {response.text[:300]}"
|
||||
|
||||
|
||||
def test_an_invalid_request_does_not_repeat_what_it_carried():
|
||||
# No "id": the request is not valid JSON-RPC, and what it carried (a connection) must not come back.
|
||||
# It has a connection of its own: a server that answers a bad request by dropping the connection (an
|
||||
# unhandled error makes uvicorn do that) must not make the NEXT check fail with "connection reset".
|
||||
marker = f"{SENTINEL}-carried"
|
||||
try:
|
||||
response = httpx.post(
|
||||
f"{BASE_URL}/messages",
|
||||
json={"jsonrpc": "2.0", "method": "tools/list", "params": {"_meta": {CONNECTION_KEY: {"field": marker}}}},
|
||||
headers=auth_headers(),
|
||||
timeout=30.0,
|
||||
)
|
||||
except httpx.TransportError:
|
||||
return # nothing came back, so nothing was repeated
|
||||
assert marker not in response.text, "the reply to an invalid request repeated the request"
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ connection
|
||||
|
||||
|
||||
def test_the_connection_schema_is_a_json_schema_object(needs_connection):
|
||||
assert needs_connection["type"] == "object"
|
||||
properties = needs_connection["properties"]
|
||||
assert isinstance(properties, dict) and properties
|
||||
assert set(needs_connection.get("required", [])) <= set(properties), "a required field is not a property"
|
||||
|
||||
|
||||
def test_the_verify_tool_is_listed(initialize, tools, needs_connection):
|
||||
verify = (initialize.get("_meta") or {}).get(VERIFY_TOOL_KEY)
|
||||
assert verify, f"initialize does not name a verify tool in _meta[{VERIFY_TOOL_KEY!r}]"
|
||||
assert verify in [t["name"] for t in tools], f"the verify tool {verify!r} is not in tools/list"
|
||||
|
||||
|
||||
def test_a_call_with_no_connection_is_refused(client, needs_connection, probe_tool):
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
response = call(client, probe_tool, None)
|
||||
assert response.json().get("error"), (
|
||||
"a call with no connection was served. The server is using its own environment for the "
|
||||
"upstream account, so every tenant would share one. Refuse it (REQUIRE_VAULT_CONNECTION)."
|
||||
)
|
||||
|
||||
|
||||
def test_a_connection_in_the_arguments_is_not_accepted(client, needs_connection, probe_tool):
|
||||
"""The credential travels in `_meta`, which the model never sees; one in `arguments` is not one."""
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
response = call(client, probe_tool, None, arguments=full_connection(needs_connection))
|
||||
assert response.json().get("error"), "a connection passed as tool arguments was accepted"
|
||||
assert not repeated(response, needs_connection), "the reply repeats a credential that was sent as an argument"
|
||||
|
||||
|
||||
def test_a_call_with_a_connection_is_not_refused_for_lacking_one(client, needs_connection, probe_tool):
|
||||
response = call(client, probe_tool, full_connection(needs_connection))
|
||||
assert response.status_code == 200
|
||||
error = response.json().get("error") or {}
|
||||
message = str(error.get("message", "")).lower()
|
||||
assert "no connection" not in message and "missing" not in message, (
|
||||
f"a complete connection was refused as incomplete: {error}"
|
||||
)
|
||||
|
||||
|
||||
def test_an_incomplete_connection_names_what_is_missing(client, needs_connection, probe_tool):
|
||||
required = list(needs_connection.get("required", []))
|
||||
if not required:
|
||||
pytest.skip("no field is required")
|
||||
connection = full_connection(needs_connection)
|
||||
dropped = required[-1]
|
||||
connection.pop(dropped)
|
||||
if not connection:
|
||||
# The only field is required, and an empty connection counts as none. Send one that has a value
|
||||
# but not the field, which is what a mistyped field name in the credential looks like.
|
||||
connection = {"not_a_field_of_this_server": "x"}
|
||||
|
||||
response = call(client, probe_tool, connection)
|
||||
error = response.json().get("error")
|
||||
assert error, f"a connection without the required field {dropped!r} was served"
|
||||
assert dropped in str(error.get("message", "")), f"the refusal does not name the missing field {dropped!r}: {error}"
|
||||
assert not repeated(response, needs_connection), "the refusal repeats a credential value"
|
||||
|
||||
|
||||
def test_no_reply_repeats_the_credential(client, needs_connection, probe_tool, tools):
|
||||
connection = full_connection(needs_connection)
|
||||
replies = [call(client, probe_tool, connection)]
|
||||
for tool in tools[:5]:
|
||||
replies.append(call(client, tool["name"], connection, arguments={"conformance": "probe"}))
|
||||
replies.append(call(client, "no_such_tool", connection))
|
||||
for response in replies:
|
||||
assert not repeated(response, needs_connection), f"a reply repeats the credential: {response.text[:300]}"
|
||||
|
||||
|
||||
def test_a_malformed_connection_is_no_better_than_none(client, needs_connection, probe_tool):
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
for bad in ("just-a-string", ["a", "list"], 42):
|
||||
params = {"name": probe_tool, "arguments": {}, "_meta": {CONNECTION_KEY: bad}}
|
||||
body = rpc(client, "tools/call", params).json()
|
||||
assert body.get("error"), f"a connection of type {type(bad).__name__} was served"
|
||||
|
||||
|
||||
def test_resources_and_prompts_are_listed_when_advertised(client, initialize):
|
||||
capabilities = initialize.get("capabilities") or {}
|
||||
if capabilities.get("resources"):
|
||||
assert isinstance(result_of(client, "resources/list")["resources"], list)
|
||||
if capabilities.get("prompts"):
|
||||
assert isinstance(result_of(client, "prompts/list")["prompts"], list)
|
||||
79
mcp-servers/cloud-knowledge.server.yaml
Normal file
79
mcp-servers/cloud-knowledge.server.yaml
Normal file
@@ -0,0 +1,79 @@
|
||||
# Hyperscaler Well-Architected guidance, for later workflows such as ALZ-F05 Target Architecture.
|
||||
# Holds Kyndryl's access, never a customer's. Store its connection tenant-wide. Queries come from fixed lists only.
|
||||
|
||||
server_id: cloud-knowledge
|
||||
name: Cloud Knowledge
|
||||
description: Well-Architected guidance from each hyperscaler's own knowledge server, searched by fixed pillar and
|
||||
topic.
|
||||
version: 0.1.1
|
||||
port: 8114
|
||||
verify_tool: cloud_check_connection
|
||||
shared_code:
|
||||
- _common/tool_support.py
|
||||
- _common/knowledge_support.py
|
||||
extra_requirements:
|
||||
- boto3==1.43.122
|
||||
connection_fields:
|
||||
- name: aws_access_key_id
|
||||
title: AWS access key ID
|
||||
description: Kyndryl's identity for the AWS MCP Server.
|
||||
required: false
|
||||
secret: false
|
||||
- name: aws_secret_access_key
|
||||
title: AWS secret access key
|
||||
description: Its secret key.
|
||||
required: false
|
||||
secret: true
|
||||
- name: google_api_key
|
||||
title: Google API key
|
||||
description: Kyndryl's key for the Developer Knowledge API.
|
||||
required: false
|
||||
secret: true
|
||||
tools:
|
||||
- name: cloud_check_connection
|
||||
display_name: Check connection
|
||||
description: Test that the knowledge servers answer. Sends no customer data.
|
||||
parameters: []
|
||||
ai_implementation: |
|
||||
async def cloud_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
results = {}
|
||||
connection = get_connection()
|
||||
for provider in KNOWLEDGE_SERVERS:
|
||||
try:
|
||||
await _knowledge_tools(provider, connection)
|
||||
results[provider] = "reachable"
|
||||
except Exception as error:
|
||||
results[provider] = type(error).__name__
|
||||
return {"ok": all(v == "reachable" for v in results.values()), "message": json.dumps(results)}
|
||||
- name: cloud_search_well_architected
|
||||
display_name: Search Well-Architected guidance
|
||||
description: Search a hyperscaler's Well-Architected guidance by pillar and topic. Both come from fixed lists,
|
||||
so no customer detail can leave the platform.
|
||||
parameters:
|
||||
- name: provider
|
||||
type: string
|
||||
description: azure, aws or gcp.
|
||||
required: true
|
||||
- name: pillar
|
||||
type: string
|
||||
description: reliability, security, cost, operations, performance or sustainability.
|
||||
required: true
|
||||
- name: topic
|
||||
type: string
|
||||
description: One of the fixed topics; an invalid value lists them.
|
||||
required: true
|
||||
ai_implementation: |
|
||||
async def cloud_search_well_architected(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
provider, pillar, topic = arguments.get("provider"), arguments.get("pillar"), arguments.get("topic")
|
||||
if provider not in KNOWLEDGE_SERVERS:
|
||||
return _refuse("invalid_argument", "provider must be azure, aws or gcp")
|
||||
if pillar not in KNOWLEDGE_PILLARS:
|
||||
return _refuse("invalid_argument", "pillar must be one of: " + ", ".join(KNOWLEDGE_PILLARS))
|
||||
if topic not in KNOWLEDGE_TOPICS:
|
||||
return _refuse("invalid_argument", "topic must be one of: " + ", ".join(KNOWLEDGE_TOPICS))
|
||||
query = f"{KNOWLEDGE_SERVERS[provider]['framework']} {pillar} {topic}"
|
||||
try:
|
||||
results = await _knowledge_search(provider, get_connection(), query)
|
||||
except Exception as error:
|
||||
return _upstream_failed(provider, error)
|
||||
return {"success": True, "data": {"provider": provider, "pillar": pillar, "topic": topic, "results": results, "collected_at": _collected_at(), "evidence_ref": _evidence_ref("cloud_search_well_architected", arguments, results)}}
|
||||
62
mcp-servers/cloud-knowledge/.env.example
Normal file
62
mcp-servers/cloud-knowledge/.env.example
Normal file
@@ -0,0 +1,62 @@
|
||||
# ============================================
|
||||
# Cloud Knowledge - Environment Variables
|
||||
# ============================================
|
||||
# Generated by Agent Builder Platform
|
||||
#
|
||||
# SETUP INSTRUCTIONS:
|
||||
# 1. Copy this file to .env: cp .env.example .env
|
||||
# 2. Generate a secure API key: openssl rand -hex 32
|
||||
# 3. Update MCP_REGISTRATION_API_KEY with the generated key
|
||||
# 4. Build the image from the Dockerfile and run it where the MCP Gateway
|
||||
# can reach it (see README.md)
|
||||
#
|
||||
# MCP GATEWAY INTEGRATION:
|
||||
# When registering with the MCP Gateway, use the URL the Gateway reaches this
|
||||
# server at; for a container on the Gateway's network, its container name:
|
||||
# http://cloud-knowledge:8114
|
||||
# ============================================
|
||||
|
||||
# Server Identity
|
||||
MCP_SERVER_NAME=Cloud Knowledge
|
||||
MCP_SERVER_ID=cloud-knowledge
|
||||
MCP_SERVER_VERSION=0.1.1
|
||||
|
||||
# Server Configuration
|
||||
MCP_SERVER_PORT=8114
|
||||
|
||||
# Logging: level (DEBUG, INFO, WARNING, ERROR) and format
|
||||
# (json = one object per line, for log stores; console = for reading by eye)
|
||||
LOG_LEVEL=INFO
|
||||
LOG_FORMAT=json
|
||||
|
||||
# ============================================
|
||||
# AUTHENTICATION (REQUIRED for production!)
|
||||
# ============================================
|
||||
# This key authenticates MCP Gateway requests to this server.
|
||||
# The Gateway stores this key and includes it in all tool/call requests.
|
||||
#
|
||||
# Generate a secure key:
|
||||
# openssl rand -hex 32
|
||||
#
|
||||
# IMPORTANT: Keep this key secret! It's stored in:
|
||||
# - This .env file (gitignored)
|
||||
# - MCP Gateway database (encrypted)
|
||||
MCP_REGISTRATION_API_KEY=<generate one: openssl rand -hex 32>
|
||||
|
||||
# Set to "false" ONLY for local development/testing
|
||||
# WARNING: Disabling auth in production is a security risk!
|
||||
REQUIRE_AUTH=true
|
||||
|
||||
# ============================================
|
||||
# CREDENTIALS FOR THE UPSTREAM (sent with each request, not set here)
|
||||
# ============================================
|
||||
# The MCP Gateway sends the tenant's credential with each call, from the Vault Service.
|
||||
# true: a call without one is refused. Set to false only for local runs, where the
|
||||
# server may use its own environment.
|
||||
REQUIRE_VAULT_CONNECTION=true
|
||||
|
||||
# ============================================
|
||||
# Add your own settings below
|
||||
# ============================================
|
||||
# Credentials for the upstream are not set here: the gateway sends them with each request.
|
||||
# EXAMPLE_SETTING=value
|
||||
15
mcp-servers/cloud-knowledge/.gitignore
vendored
Normal file
15
mcp-servers/cloud-knowledge/.gitignore
vendored
Normal file
@@ -0,0 +1,15 @@
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
.venv/
|
||||
venv/
|
||||
.pytest_cache/
|
||||
|
||||
# Editors
|
||||
.vscode/
|
||||
.idea/
|
||||
47
mcp-servers/cloud-knowledge/Dockerfile
Normal file
47
mcp-servers/cloud-knowledge/Dockerfile
Normal file
@@ -0,0 +1,47 @@
|
||||
# MCP Server Dockerfile
|
||||
# Generated by Agent Builder Platform (template 1.1.0)
|
||||
#
|
||||
# Built on the platform's MCP server base image: Chainguard Python with the
|
||||
# packages in requirements.txt already installed, a non-root user (1000) and
|
||||
# no pip. This image adds only the server's own files.
|
||||
#
|
||||
# docker build -t <server>:<version> .
|
||||
# docker build --build-arg BASE_IMAGE=<local base image> -t ... .
|
||||
ARG BASE_IMAGE=kyndryl.jfrog.io/kc-ai-agent-factory-docker-local/mcp-server-base:1.1.0
|
||||
|
||||
# Stage 1: the server's extra Python packages, if requirements.txt lists any.
|
||||
# The base image's build image (<base image>-build: the base image plus uv) installs
|
||||
# them with its vendor-install script: only the packages added go on to
|
||||
# /vendor, and one that would change a package the base image already has stops
|
||||
# the build. uv never reaches the server's image.
|
||||
FROM ${BASE_IMAGE}-build AS vendor
|
||||
COPY requirements.txt constraints.txt /tmp/
|
||||
RUN vendor-install /tmp/requirements.txt /vendor /tmp/constraints.txt
|
||||
|
||||
# Stage 2: the server: the base image, its extra packages and its files.
|
||||
FROM ${BASE_IMAGE}
|
||||
|
||||
LABEL maintainer="Agent Builder Platform"
|
||||
LABEL description="Well-Architected guidance from each hyperscaler's own knowledge server, searched by fixed pillar and topic."
|
||||
LABEL version="0.1.1"
|
||||
LABEL server.id="cloud-knowledge"
|
||||
LABEL template.version="1.1.0"
|
||||
|
||||
COPY --from=vendor /vendor /app/vendor/
|
||||
COPY server.py mcp_connection.py /app/
|
||||
|
||||
# Environment
|
||||
# The ConfigMap's SERVER_PORT overrides this, so the container, Service and probes agree
|
||||
ENV SERVER_PORT=8114
|
||||
ENV LOG_LEVEL=INFO
|
||||
ENV LOG_FORMAT=json
|
||||
|
||||
# Expose port
|
||||
EXPOSE 8114
|
||||
|
||||
# Health check
|
||||
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
||||
CMD python -c "import os, urllib.request; urllib.request.urlopen('http://localhost:%s/health' % (os.getenv('MCP_SERVER_PORT') or os.getenv('SERVER_PORT') or '8114'))" || exit 1
|
||||
|
||||
# Run the server
|
||||
CMD ["python", "server.py"]
|
||||
188
mcp-servers/cloud-knowledge/README.md
Normal file
188
mcp-servers/cloud-knowledge/README.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Cloud Knowledge
|
||||
|
||||
Well-Architected guidance from each hyperscaler's own knowledge server, searched by fixed pillar and topic.
|
||||
|
||||
**Version:** 0.1.1
|
||||
**Server ID:** cloud-knowledge
|
||||
**Port:** 8114
|
||||
|
||||
---
|
||||
|
||||
## 🚀 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>:8114`.
|
||||
|
||||
### 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
|
||||
|
||||
- **cloud_check_connection**: Test that the knowledge servers answer. Sends no customer data.
|
||||
- **cloud_search_well_architected**: Search a hyperscaler's Well-Architected guidance by pillar and topic. Both come from fixed lists, so no customer detail can leave the platform.
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Authentication
|
||||
|
||||
This server uses Bearer token authentication for MCP protocol messages.
|
||||
|
||||
```bash
|
||||
# Test with authentication
|
||||
curl -X POST http://localhost:8114/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:8114`)
|
||||
- **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 |
|
||||
|---|---|---|
|
||||
| `aws_access_key_id` | no | no |
|
||||
| `aws_secret_access_key` | no | yes |
|
||||
| `google_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:8114 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 `cloud-knowledge/`, then add it to
|
||||
`mcp_servers_to_deploy.yaml` in that repository with the instances it should
|
||||
run on:
|
||||
|
||||
```yaml
|
||||
- name: "cloud-knowledge"
|
||||
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:8114/health
|
||||
|
||||
# List tools
|
||||
curl -X POST http://localhost:8114/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)
|
||||
29
mcp-servers/cloud-knowledge/constraints.txt
Normal file
29
mcp-servers/cloud-knowledge/constraints.txt
Normal file
@@ -0,0 +1,29 @@
|
||||
# Every package installed in a generated MCP server, pinned to one exact version:
|
||||
# the ones requirements.txt names and everything they bring in. They are
|
||||
# installed in the MCP server base image (Dockerfile.base), so every server
|
||||
# built from this template gets the same versions as the platform's own
|
||||
# services.
|
||||
annotated-doc==0.0.5
|
||||
annotated-types==0.8.0
|
||||
anyio==4.15.1
|
||||
certifi==2026.10.19
|
||||
click==8.5.0
|
||||
fastapi==0.143.2
|
||||
h11==0.16.0
|
||||
httpcore==1.0.9
|
||||
httptools==0.9.0
|
||||
httpx==0.28.1
|
||||
idna==3.20
|
||||
opentelemetry-api==1.45.1
|
||||
pydantic==2.14.1
|
||||
pydantic-core==2.50.1
|
||||
python-dotenv==1.2.4
|
||||
pyyaml==6.0.3
|
||||
starlette==1.8.0
|
||||
structlog==26.1.0
|
||||
typing-extensions==4.16.0
|
||||
typing-inspection==0.4.4
|
||||
uvicorn==0.54.0
|
||||
uvloop==0.23.0
|
||||
watchfiles==1.3.0
|
||||
websockets==16.1.1
|
||||
25
mcp-servers/cloud-knowledge/kubernetes/configmap.yaml
Normal file
25
mcp-servers/cloud-knowledge/kubernetes/configmap.yaml
Normal file
@@ -0,0 +1,25 @@
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>-config # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
data:
|
||||
|
||||
# Read by the CI/CD pipeline: the server's name, and the port it listens on
|
||||
# (used for the container, the Service and the probes)
|
||||
MCP_SERVER_NAME: "cloud-knowledge"
|
||||
SERVER_PORT: "8114"
|
||||
|
||||
# One JSON object per line; LOG_FORMAT=console prints readable lines
|
||||
LOG_LEVEL: "INFO"
|
||||
LOG_FORMAT: "json"
|
||||
|
||||
# Leave on. The Gateway authenticates to this server with a bearer token, and
|
||||
# turning this off makes every tool callable by anything that can reach the
|
||||
# pod inside the cluster.
|
||||
REQUIRE_AUTH: "true"
|
||||
|
||||
# Refuse a call that arrives without the tenant's credential from the Vault Service
|
||||
REQUIRE_VAULT_CONNECTION: "true"
|
||||
|
||||
# Add your own settings here
|
||||
# EXAMPLE_SETTING: "value"
|
||||
71
mcp-servers/cloud-knowledge/kubernetes/deployment.yaml
Normal file
71
mcp-servers/cloud-knowledge/kubernetes/deployment.yaml
Normal file
@@ -0,0 +1,71 @@
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
imagePullSecrets:
|
||||
- name: jfrog-secret
|
||||
containers:
|
||||
- name: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
image: <placeholder_for_image> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
imagePullPolicy: Always
|
||||
ports:
|
||||
- containerPort: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
name: http
|
||||
# Load all environment variables from ConfigMap
|
||||
envFrom:
|
||||
- secretRef:
|
||||
name: <placeholder_for_mcp_server_name>-secrets # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
optional: true # Won't fail if secret doesn't exist
|
||||
- secretRef:
|
||||
name: <placeholder_for_mcp_server_name>-dotenv-secrets # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
optional: true # Won't fail if secret doesn't exist
|
||||
- configMapRef:
|
||||
name: <placeholder_for_mcp_server_name>-config # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
# The registration key and server id are generated by the CI/CD pipeline;
|
||||
# the server needs the key to accept the Gateway's calls
|
||||
env:
|
||||
- name: MCP_REGISTRATION_API_KEY
|
||||
value: "<placeholder_for_registration_api_key>" # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
- name: MCP_SERVER_ID
|
||||
value: "<placeholder_for_server_id>" # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
resources:
|
||||
requests:
|
||||
memory: "128Mi"
|
||||
cpu: "10m"
|
||||
limits:
|
||||
memory: "1024Mi"
|
||||
cpu: "1000m"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
initialDelaySeconds: 30 # Wait X seconds before first check
|
||||
periodSeconds: 15 # Check every X seconds
|
||||
timeoutSeconds: 10 # Each check can take up to X seconds to respond
|
||||
failureThreshold: 5 # Allow X consecutive failures before marking unhealthy
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
initialDelaySeconds: 30 # Wait X seconds before first check
|
||||
periodSeconds: 15 # Check every X seconds
|
||||
timeoutSeconds: 10 # Each check can take up to X seconds to respond
|
||||
failureThreshold: 5 # Allow X consecutive failures before marking unhealthy
|
||||
|
||||
# volumes:
|
||||
# - name: execution-storage
|
||||
# persistentVolumeClaim:
|
||||
# claimName: execution-storage-pvc # Same PVC name as core-components
|
||||
20
mcp-servers/cloud-knowledge/kubernetes/kustomization.yaml
Normal file
20
mcp-servers/cloud-knowledge/kubernetes/kustomization.yaml
Normal file
@@ -0,0 +1,20 @@
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- namespace.yaml
|
||||
- deployment.yaml
|
||||
- service.yaml
|
||||
- configmap.yaml
|
||||
- secretnames.yaml
|
||||
|
||||
# Optionally add common labels
|
||||
|
||||
# Namespace for all resources
|
||||
namespace: mcp-servers
|
||||
labels:
|
||||
- includeSelectors: true
|
||||
pairs:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
environment: production
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
7
mcp-servers/cloud-knowledge/kubernetes/namespace.yaml
Normal file
7
mcp-servers/cloud-knowledge/kubernetes/namespace.yaml
Normal file
@@ -0,0 +1,7 @@
|
||||
# Do not modify this file, otherwise CI/CD pipeline will fail
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: mcp-servers
|
||||
labels:
|
||||
name: mcp-servers
|
||||
18
mcp-servers/cloud-knowledge/kubernetes/secretnames.yaml
Normal file
18
mcp-servers/cloud-knowledge/kubernetes/secretnames.yaml
Normal file
@@ -0,0 +1,18 @@
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>-secrets
|
||||
type: Opaque
|
||||
data:
|
||||
# Base64 encoded values (NOT RECOMMENDED for sensitive data)
|
||||
# To encode: echo -n 'your-secret-value' | base64
|
||||
# Example: api-key: eW91ci1hcGkta2V5LXZhbHVl
|
||||
|
||||
stringData:
|
||||
# Plain text values saved on GitHub Secrets (RECOMMENDED)
|
||||
# Example:
|
||||
#
|
||||
# DB_PASSWORD: ${DB_PASSWORD_GITHUB_SECRET}
|
||||
# ANOTHER_SECRET: ${ANOTHER_GITHUB_SECRET}
|
||||
#
|
||||
# ${DB_PASSWORD_GITHUB_SECRET} and ${ANOTHER_GITHUB_SECRET} must exist as GitHub Secrets
|
||||
33
mcp-servers/cloud-knowledge/kubernetes/service.yaml
Normal file
33
mcp-servers/cloud-knowledge/kubernetes/service.yaml
Normal file
@@ -0,0 +1,33 @@
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name>
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
type: ClusterIP
|
||||
ports:
|
||||
- port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
targetPort: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
protocol: TCP
|
||||
name: http
|
||||
selector:
|
||||
app: <placeholder_for_mcp_server_name>
|
||||
---
|
||||
# Optional: LoadBalancer service for external access
|
||||
# apiVersion: v1
|
||||
# kind: Service
|
||||
# metadata:
|
||||
# name: <placeholder_for_mcp_server_name>-external
|
||||
# labels:
|
||||
# app: <placeholder_for_mcp_server_name>
|
||||
# spec:
|
||||
# type: LoadBalancer
|
||||
# ports:
|
||||
# - port: 80
|
||||
# targetPort: 8080
|
||||
# protocol: TCP
|
||||
# name: http
|
||||
# selector:
|
||||
# app: <placeholder_for_mcp_server_name>
|
||||
256
mcp-servers/cloud-knowledge/mcp_connection.py
Normal file
256
mcp-servers/cloud-knowledge/mcp_connection.py
Normal file
@@ -0,0 +1,256 @@
|
||||
"""The connection a request carries: which upstream account this call is for.
|
||||
|
||||
An MCP server that talks to a third-party system needs that system's address and credentials. Taking
|
||||
them from environment variables makes one process serve one account for ever. Here the MCP Gateway
|
||||
sends them with each call, from the Vault Service, in MCP's own `_meta` field, under our vendor prefix:
|
||||
|
||||
initialize result _meta["com.kyndryl.mcp/connection-schema"] what this server needs (JSON Schema)
|
||||
_meta["com.kyndryl.mcp/verify-tool"] the tool that tests a connection
|
||||
tools/call, resources/read, prompts/get
|
||||
params._meta["com.kyndryl.mcp/connection"] the values, matching that schema
|
||||
|
||||
`_meta` is where the specification tells implementations to put their own data, so a client that does
|
||||
not know these keys ignores them. The values never travel in `arguments`, which is what the model
|
||||
writes and reads, so a credential cannot enter the model's context.
|
||||
|
||||
The connection is bound for the life of one request and read with `active()`. It is None when the caller
|
||||
sent nothing; whether the server may then use its own environment is decided in server.py
|
||||
(REQUIRE_VAULT_CONNECTION, which is on by default).
|
||||
|
||||
WHAT IS STANDARD AND WHAT IS OURS
|
||||
---------------------------------
|
||||
The mechanism is standard. `_meta` is the specification's sanctioned place for implementation-specific
|
||||
data, with formal key-naming rules (2026-07-28, "General fields / _meta"):
|
||||
|
||||
Prefix ... SHOULD use reverse DNS notation. Any prefix where the second label is
|
||||
`modelcontextprotocol` or `mcp` is reserved for MCP use ... third-party extensions use their own
|
||||
vendor prefix.
|
||||
|
||||
`com.kyndryl.mcp/` satisfies that: the second label is `kyndryl`, so it is a legitimate vendor prefix and
|
||||
not reserved. A client that does not recognise our keys ignores them, which is exactly what `_meta` is for.
|
||||
The value carried is a *separate* upstream credential, never the caller's own token (the specification
|
||||
says a server MUST NOT pass through the token it received from its client).
|
||||
|
||||
Only the three key names and the shape of their payloads are ours. When SEP-2127 (MCP Server Card) lands,
|
||||
the schema is what moves onto the card, and the key names are the only thing that changes.
|
||||
|
||||
The third key, VERIFY_TOOL_KEY, adds very little. Checking a credential is a plain `tools/call` against an
|
||||
ordinary tool that appears in `tools/list` like any other: no new method, no new transport. The only
|
||||
question that needed answering is WHICH tool, and the alternative was for the gateway to guess by name. A
|
||||
server that advertises nothing here is simply not verifiable.
|
||||
|
||||
STATELESSNESS
|
||||
-------------
|
||||
The 2026-07-28 specification made MCP explicitly stateless: "Servers MUST NOT rely on prior requests over
|
||||
the same connection to establish context ... Every request supplies this metadata in its _meta field."
|
||||
A module-level connection built once at import is exactly the state the specification tells servers not to
|
||||
keep. Binding the connection per request is therefore not only what multi-tenancy needs, it is what the
|
||||
protocol asks for.
|
||||
|
||||
HOW IT IS USED (server.py does all of this; a tool only calls get_connection())
|
||||
------------------------------------------------------------------------------
|
||||
import mcp_connection
|
||||
|
||||
# advertise, in the initialize result
|
||||
result["_meta"] = mcp_connection.schema_meta(CONNECTION_SCHEMA, verify_tool="verify_connection")
|
||||
|
||||
# bind, for the life of one request
|
||||
token = mcp_connection.bind(mcp_connection.from_params(request.params))
|
||||
try:
|
||||
... # mcp_connection.active() anywhere below
|
||||
finally:
|
||||
mcp_connection.unbind(token)
|
||||
|
||||
LOGS AND ERROR MESSAGES
|
||||
-----------------------
|
||||
`scrub()` is applied to every log line, and to the `error` text of a failed tool call, so the connection's
|
||||
values and credential-looking URL parameters (`?key=...`) never leave the process. `redact()` does the
|
||||
connection values alone. Neither is applied to a successful result: a presigned URL a tool returns on
|
||||
purpose must survive.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextvars
|
||||
import hashlib
|
||||
import hmac
|
||||
import json
|
||||
import re
|
||||
import secrets
|
||||
from typing import Any, Callable, Dict, List, Optional
|
||||
|
||||
VENDOR = "com.kyndryl.mcp"
|
||||
SCHEMA_KEY = f"{VENDOR}/connection-schema"
|
||||
CONNECTION_KEY = f"{VENDOR}/connection"
|
||||
VERIFY_TOOL_KEY = f"{VENDOR}/verify-tool"
|
||||
|
||||
_active: contextvars.ContextVar[Optional[Dict[str, Any]]] = contextvars.ContextVar(
|
||||
"mcp_connection", default=None
|
||||
)
|
||||
|
||||
# Per process, so a fingerprint in a log cannot be checked against a guessed credential offline
|
||||
_FINGERPRINT_KEY = secrets.token_bytes(32)
|
||||
|
||||
|
||||
def schema_meta(schema: Dict[str, Any], verify_tool: Optional[str] = None) -> Dict[str, Any]:
|
||||
"""The `_meta` object that advertises `schema` on an initialize result."""
|
||||
meta: Dict[str, Any] = {SCHEMA_KEY: schema}
|
||||
if verify_tool:
|
||||
meta[VERIFY_TOOL_KEY] = verify_tool
|
||||
return meta
|
||||
|
||||
|
||||
def verify_tool_from_initialize(result: Optional[Dict[str, Any]]) -> Optional[str]:
|
||||
"""The verify tool an initialize result advertises, or None.
|
||||
|
||||
The reader half of schema_meta, here rather than in the gateway so the two ends of the key cannot
|
||||
drift apart.
|
||||
"""
|
||||
if not isinstance(result, dict):
|
||||
return None
|
||||
meta = result.get("_meta")
|
||||
if not isinstance(meta, dict):
|
||||
return None
|
||||
name = meta.get(VERIFY_TOOL_KEY)
|
||||
return name if isinstance(name, str) and name.strip() else None
|
||||
|
||||
|
||||
def from_params(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
|
||||
"""The connection in a request's `params._meta`, or None.
|
||||
|
||||
Anything that is not an object counts as absent: a malformed connection must not be more
|
||||
powerful than none at all.
|
||||
"""
|
||||
if not isinstance(params, dict):
|
||||
return None
|
||||
meta = params.get("_meta")
|
||||
if not isinstance(meta, dict):
|
||||
return None
|
||||
profile = meta.get(CONNECTION_KEY)
|
||||
return profile if isinstance(profile, dict) and profile else None
|
||||
|
||||
|
||||
def bind(profile: Optional[Dict[str, Any]]) -> contextvars.Token:
|
||||
"""Make `profile` the connection for this request."""
|
||||
return _active.set(profile)
|
||||
|
||||
|
||||
def unbind(token: contextvars.Token) -> None:
|
||||
try:
|
||||
_active.reset(token)
|
||||
except ValueError:
|
||||
_active.set(None)
|
||||
|
||||
|
||||
def active() -> Optional[Dict[str, Any]]:
|
||||
"""The connection for this request, or None."""
|
||||
return _active.get()
|
||||
|
||||
|
||||
def fingerprint(profile: Optional[Dict[str, Any]]) -> str:
|
||||
"""A short id for a connection, safe to log and to cache on; the credential never is the key."""
|
||||
if not profile:
|
||||
return "env"
|
||||
canonical = json.dumps(profile, sort_keys=True, separators=(",", ":"), default=str)
|
||||
return hmac.new(_FINGERPRINT_KEY, canonical.encode("utf-8"), hashlib.sha256).hexdigest()[:16]
|
||||
|
||||
|
||||
def redact(text: Any) -> str:
|
||||
"""`text` with every value of this request's connection replaced, for logs and error replies.
|
||||
|
||||
A tool can put a credential in an exception message without meaning to. Values shorter than four
|
||||
characters are left alone: replacing them would garble ordinary text.
|
||||
"""
|
||||
result = str(text)
|
||||
values = [v for v in (active() or {}).values() if isinstance(v, str) and len(v) >= 4]
|
||||
for value in sorted(values, key=len, reverse=True):
|
||||
result = result.replace(value, "[redacted]")
|
||||
return result
|
||||
|
||||
|
||||
# Query parameters that carry a credential in the URL of an upstream request
|
||||
_URL_CREDENTIAL = re.compile(
|
||||
r"([?&;](?:api[_-]?key|apikey|key|token|access[_-]?token|auth|secret|password|passwd|"
|
||||
r"client[_-]?secret|appid|app[_-]?id|sig|signature)=)[^&\s\"'#<>]+",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
|
||||
def scrub(value: Any, _depth: int = 0) -> Any:
|
||||
"""`value` with credentials taken out, for anything that is logged or sent back to a caller.
|
||||
|
||||
Strings lose the request's connection values and the value of any credential query parameter in a
|
||||
URL (`?key=...`); dicts, lists and tuples are scrubbed inside. Anything else is returned as it is.
|
||||
Not for tool results in general: a presigned URL a tool returns on purpose would be damaged.
|
||||
"""
|
||||
if isinstance(value, str):
|
||||
return _URL_CREDENTIAL.sub(r"\1[redacted]", redact(value))
|
||||
if _depth > 5:
|
||||
return value
|
||||
if isinstance(value, dict):
|
||||
return {k: scrub(v, _depth + 1) for k, v in value.items()}
|
||||
if isinstance(value, (list, tuple)):
|
||||
return type(value)(scrub(v, _depth + 1) for v in value)
|
||||
return value
|
||||
|
||||
|
||||
def missing_fields(profile: Optional[Dict[str, Any]], schema: Dict[str, Any]) -> List[str]:
|
||||
"""The required fields of `schema` that `profile` does not supply."""
|
||||
if not profile:
|
||||
return []
|
||||
required = schema.get("required") or []
|
||||
return [name for name in required if not str(profile.get(name) or "").strip()]
|
||||
|
||||
|
||||
def install_invalid_request_handler(app: Any, on_invalid: Optional[Callable[[str], None]] = None) -> None:
|
||||
"""Answer a request that is not valid JSON-RPC with a JSON-RPC error that does not repeat the request.
|
||||
|
||||
FastAPI's own answer (HTTP 422) repeats the request body under "input". The body is where the gateway puts
|
||||
the tenant's connection, so a request that is merely malformed (no "id", say) would get the credential back
|
||||
in the reply, and in the log of anything that records replies. The status stays 422; the body is a JSON-RPC
|
||||
error (-32600) that names only the fields at fault. `on_invalid`, if given, is called with that text, already
|
||||
reduced to harmless characters, so the caller can log it in its own style.
|
||||
|
||||
Call it once, right after `app = FastAPI(...)`. FastAPI is imported here, not at module level, so the rest of
|
||||
this module stays importable without it.
|
||||
"""
|
||||
from fastapi.exceptions import RequestValidationError
|
||||
from fastapi.responses import JSONResponse
|
||||
|
||||
@app.exception_handler(RequestValidationError)
|
||||
async def invalid_request(request, exc):
|
||||
names = {
|
||||
"body" if error.get("type") == "json_invalid" else ".".join(str(p) for p in error.get("loc", ())[1:]) or "body"
|
||||
for error in exc.errors()
|
||||
}
|
||||
fields = re.sub(r"[^\w.\-, ]", "?", ", ".join(sorted(names)))[:200]
|
||||
if on_invalid is not None:
|
||||
on_invalid(fields)
|
||||
return JSONResponse(
|
||||
status_code=422,
|
||||
content={
|
||||
"jsonrpc": "2.0",
|
||||
"id": None,
|
||||
"result": None,
|
||||
"error": {"code": -32600, "message": "Invalid request: check " + fields},
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"install_invalid_request_handler",
|
||||
"VENDOR",
|
||||
"SCHEMA_KEY",
|
||||
"CONNECTION_KEY",
|
||||
"VERIFY_TOOL_KEY",
|
||||
"schema_meta",
|
||||
"verify_tool_from_initialize",
|
||||
"from_params",
|
||||
"bind",
|
||||
"unbind",
|
||||
"active",
|
||||
"fingerprint",
|
||||
"redact",
|
||||
"scrub",
|
||||
"missing_fields",
|
||||
]
|
||||
42
mcp-servers/cloud-knowledge/requirements.txt
Normal file
42
mcp-servers/cloud-knowledge/requirements.txt
Normal file
@@ -0,0 +1,42 @@
|
||||
# MCP Server Dependencies
|
||||
# Generated by Agent Builder Platform
|
||||
|
||||
# Each dependency is pinned to one exact version, and constraints.txt pins everything they bring
|
||||
# in, so two builds of the same server get the same packages -- the same versions as the
|
||||
# platform's own services. The packages below are already installed in the MCP server base
|
||||
# image the Dockerfile builds on; a package added to this file is installed on top of them at
|
||||
# build time. Changing the version of one the base has stops the build: the base image moves
|
||||
# those, with the template.
|
||||
|
||||
# Core Framework
|
||||
# FastAPI - Modern web framework for MCP server
|
||||
fastapi==0.143.2
|
||||
|
||||
# ASGI Server
|
||||
# Uvicorn - Lightning-fast ASGI server
|
||||
uvicorn[standard]==0.54.0
|
||||
|
||||
# Data Validation
|
||||
# Pydantic - Data validation using Python type hints
|
||||
pydantic==2.14.1
|
||||
|
||||
# HTTP Client
|
||||
# HTTPX - Async HTTP client for API calls
|
||||
httpx==0.28.1
|
||||
|
||||
# Environment Variables
|
||||
# python-dotenv - Load environment from .env files
|
||||
python-dotenv==1.2.4
|
||||
|
||||
# Structured Logging
|
||||
# structlog - JSON log lines (see LOG_FORMAT in server.py)
|
||||
structlog==26.1.0
|
||||
|
||||
# Optional: Add your custom dependencies below
|
||||
# requests>=2.31.0
|
||||
# aiofiles>=23.2.1
|
||||
# sqlalchemy>=2.0.0
|
||||
# redis>=5.0.0
|
||||
|
||||
# Added by this server's definition
|
||||
boto3==1.43.122
|
||||
1046
mcp-servers/cloud-knowledge/server.py
Normal file
1046
mcp-servers/cloud-knowledge/server.py
Normal file
File diff suppressed because it is too large
Load Diff
360
mcp-servers/cloud-knowledge/tests/test_conformance.py
Normal file
360
mcp-servers/cloud-knowledge/tests/test_conformance.py
Normal file
@@ -0,0 +1,360 @@
|
||||
"""Conformance checks for an MCP server that takes its upstream credentials from the MCP Gateway.
|
||||
|
||||
Run these against a running server before you push it. They need only `pytest` and `httpx`, import
|
||||
nothing from the server and talk to it over HTTP, so they work on a server from the MCP Server
|
||||
Builder and on one written by hand.
|
||||
|
||||
pip install pytest httpx
|
||||
MCP_SERVER_URL=http://localhost:8100 MCP_REGISTRATION_API_KEY=<the server's key> pytest tests/ -v
|
||||
|
||||
What is checked, and why:
|
||||
|
||||
Protocol the server answers /health, refuses callers without its key, and speaks JSON-RPC
|
||||
correctly (initialize, tools/list, ids echoed, errors as errors).
|
||||
Connection a server that needs an upstream account says so in its initialize result
|
||||
(`_meta["com.kyndryl.mcp/connection-schema"]`) and takes the account from each
|
||||
request (`params._meta["com.kyndryl.mcp/connection"]`), not from its own environment.
|
||||
Such a server refuses a call that carries none (fail closed), reports which required
|
||||
field is missing, takes nothing from `arguments`, and never repeats a credential in a
|
||||
reply (the values of fields marked `writeOnly`; every value if none is marked). A server that needs no account skips these checks.
|
||||
|
||||
Settings (environment variables):
|
||||
|
||||
MCP_SERVER_URL default http://localhost:8100
|
||||
MCP_REGISTRATION_API_KEY the key the server was started with (required unless the
|
||||
server has authentication switched off)
|
||||
CONFORMANCE_EXPECT_FAIL_CLOSED default true. Set false only for a server you run locally
|
||||
with REQUIRE_VAULT_CONNECTION=false, so that checks which
|
||||
need a refusal are skipped rather than failed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import secrets
|
||||
import uuid
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
VENDOR = "com.kyndryl.mcp"
|
||||
SCHEMA_KEY = f"{VENDOR}/connection-schema"
|
||||
VERIFY_TOOL_KEY = f"{VENDOR}/verify-tool"
|
||||
CONNECTION_KEY = f"{VENDOR}/connection"
|
||||
|
||||
BASE_URL = os.getenv("MCP_SERVER_URL", "http://localhost:8100").rstrip("/")
|
||||
API_KEY = os.getenv("MCP_REGISTRATION_API_KEY", "")
|
||||
EXPECT_FAIL_CLOSED = os.getenv("CONFORMANCE_EXPECT_FAIL_CLOSED", "true").strip().lower() != "false"
|
||||
|
||||
# A value no server could contain by accident, so finding it in a reply means the server repeated it.
|
||||
SENTINEL = f"sentinel-{secrets.token_hex(6)}"
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ helpers
|
||||
|
||||
|
||||
def auth_headers(key: Optional[str] = None) -> Dict[str, str]:
|
||||
key = API_KEY if key is None else key
|
||||
return {"Authorization": f"Bearer {key}"} if key else {}
|
||||
|
||||
|
||||
def rpc(
|
||||
client: httpx.Client,
|
||||
method: str,
|
||||
params: Optional[Dict[str, Any]] = None,
|
||||
*,
|
||||
request_id: Any = "1",
|
||||
headers: Optional[Dict[str, str]] = None,
|
||||
) -> httpx.Response:
|
||||
return client.post(
|
||||
"/messages",
|
||||
json={"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}},
|
||||
headers=auth_headers() if headers is None else headers,
|
||||
)
|
||||
|
||||
|
||||
def result_of(client: httpx.Client, method: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
||||
response = rpc(client, method, params)
|
||||
assert response.status_code == 200, f"{method} answered HTTP {response.status_code}: {response.text[:300]}"
|
||||
body = response.json()
|
||||
assert not body.get("error"), f"{method} returned an error: {body['error']}"
|
||||
return body["result"]
|
||||
|
||||
|
||||
def with_connection(params: Dict[str, Any], connection: Optional[Dict[str, Any]]) -> Dict[str, Any]:
|
||||
if connection is None:
|
||||
return params
|
||||
return {**params, "_meta": {CONNECTION_KEY: connection}}
|
||||
|
||||
|
||||
def value_for(name: str, spec: Dict[str, Any]) -> Any:
|
||||
"""A value of the right shape for a connection field, carrying the sentinel."""
|
||||
kind = spec.get("type", "string")
|
||||
if kind == "string" and spec.get("format") == "uri":
|
||||
return f"https://{SENTINEL}.invalid"
|
||||
if kind == "integer":
|
||||
return 12345
|
||||
if kind == "boolean":
|
||||
return True
|
||||
return f"{SENTINEL}-{name}"
|
||||
|
||||
|
||||
def full_connection(schema: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return {name: value_for(name, spec) for name, spec in (schema.get("properties") or {}).items()}
|
||||
|
||||
|
||||
def secret_values(schema: Dict[str, Any]) -> List[str]:
|
||||
"""The sent values that must never come back: those of fields marked secret (`writeOnly`).
|
||||
|
||||
A tool may repeat a base URL or a region. If the server marks no field secret, every value is
|
||||
treated as one, because then nothing says which are safe to repeat.
|
||||
"""
|
||||
connection = full_connection(schema)
|
||||
properties = schema.get("properties") or {}
|
||||
marked = [n for n, spec in properties.items() if spec.get("writeOnly")]
|
||||
return [str(connection[n]) for n in (marked or list(properties))]
|
||||
|
||||
|
||||
def repeated(response: httpx.Response, schema: Dict[str, Any]) -> List[str]:
|
||||
return [v for v in secret_values(schema) if v in response.text]
|
||||
|
||||
|
||||
def _string_values(node: Any) -> List[str]:
|
||||
"""Every string anywhere in a JSON value."""
|
||||
if isinstance(node, str):
|
||||
return [node]
|
||||
if isinstance(node, dict):
|
||||
return [v for item in node.values() for v in _string_values(item)]
|
||||
if isinstance(node, list):
|
||||
return [v for item in node for v in _string_values(item)]
|
||||
return []
|
||||
|
||||
|
||||
def call(client: httpx.Client, tool: str, connection: Optional[Dict[str, Any]], arguments: Optional[Dict] = None):
|
||||
return rpc(client, "tools/call", with_connection({"name": tool, "arguments": arguments or {}}, connection))
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ fixtures
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def client():
|
||||
with httpx.Client(base_url=BASE_URL, timeout=30.0) as session:
|
||||
try:
|
||||
session.get("/health")
|
||||
except httpx.HTTPError as error:
|
||||
pytest.exit(f"Cannot reach the server at {BASE_URL}: {error}. Start it, or set MCP_SERVER_URL.", 2)
|
||||
yield session
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def initialize(client) -> Dict[str, Any]:
|
||||
return result_of(client, "initialize", {"protocolVersion": "1.0.0", "clientInfo": {"name": "conformance"}})
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def tools(client) -> List[Dict[str, Any]]:
|
||||
return result_of(client, "tools/list")["tools"]
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def schema(initialize) -> Optional[Dict[str, Any]]:
|
||||
return (initialize.get("_meta") or {}).get(SCHEMA_KEY)
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def needs_connection(schema) -> Dict[str, Any]:
|
||||
if not schema or not schema.get("properties"):
|
||||
pytest.skip("the server advertises no connection fields, so it takes no per-request credentials")
|
||||
return schema
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def probe_tool(initialize, tools) -> str:
|
||||
"""The tool to call in the connection checks: the verify tool when there is one."""
|
||||
verify = (initialize.get("_meta") or {}).get(VERIFY_TOOL_KEY)
|
||||
if verify:
|
||||
return verify
|
||||
assert tools, "the server lists no tools to call"
|
||||
return tools[0]["name"]
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ protocol
|
||||
|
||||
|
||||
def test_health_answers(client):
|
||||
assert client.get("/health").status_code == 200
|
||||
|
||||
|
||||
def test_the_public_auth_endpoint_reveals_no_key(client):
|
||||
response = client.get("/.well-known/mcp-auth")
|
||||
if response.status_code == 404:
|
||||
pytest.skip("the server has no /.well-known/mcp-auth endpoint")
|
||||
assert response.status_code == 200
|
||||
if API_KEY:
|
||||
# A value that equals the key is always a leak. A short key can also appear inside ordinary words
|
||||
# ("nc" in "auth_required"), so searching the text for it is only meaningful for a real-length key.
|
||||
assert API_KEY not in _string_values(response.json()), "/.well-known/mcp-auth returns the server's key"
|
||||
if len(API_KEY) >= 12:
|
||||
assert API_KEY not in response.text, "/.well-known/mcp-auth returns the server's key"
|
||||
|
||||
|
||||
def test_a_call_without_the_servers_key_is_refused(client):
|
||||
response = rpc(client, "tools/list", headers={})
|
||||
assert response.status_code in (401, 403), f"answered HTTP {response.status_code} to a caller with no key"
|
||||
|
||||
|
||||
def test_a_call_with_the_wrong_key_is_refused(client):
|
||||
response = rpc(client, "tools/list", headers=auth_headers("not-the-key-" + uuid.uuid4().hex))
|
||||
assert response.status_code in (401, 403), f"answered HTTP {response.status_code} to a caller with the wrong key"
|
||||
|
||||
|
||||
def test_initialize_describes_the_server(initialize):
|
||||
assert initialize["serverInfo"]["name"]
|
||||
assert isinstance(initialize.get("capabilities"), dict)
|
||||
|
||||
|
||||
def test_tools_have_a_name_a_description_and_an_object_schema(tools):
|
||||
assert isinstance(tools, list)
|
||||
names = [t["name"] for t in tools]
|
||||
assert len(names) == len(set(names)), "two tools share a name"
|
||||
for tool in tools:
|
||||
assert tool["name"] and tool.get("description"), f"tool {tool.get('name')!r} lacks a name or description"
|
||||
assert tool["inputSchema"]["type"] == "object", f"{tool['name']} has no object inputSchema"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("request_id", ["conformance-1", 7])
|
||||
def test_the_reply_echoes_the_request_id(client, request_id):
|
||||
response = rpc(client, "tools/list", request_id=request_id)
|
||||
assert response.status_code == 200
|
||||
assert response.json()["id"] == request_id
|
||||
|
||||
|
||||
def test_an_unknown_method_is_an_error_not_a_crash(client):
|
||||
response = rpc(client, "no/such/method")
|
||||
assert response.status_code == 200
|
||||
assert response.json().get("error"), "an unknown method returned no error"
|
||||
|
||||
|
||||
def test_an_unknown_tool_is_an_error_not_a_crash(client):
|
||||
response = rpc(client, "tools/call", {"name": f"no_such_tool_{uuid.uuid4().hex[:8]}", "arguments": {}})
|
||||
assert response.status_code == 200
|
||||
assert response.json().get("error"), "an unknown tool returned no error"
|
||||
|
||||
|
||||
def test_arguments_that_are_not_an_object_are_the_callers_mistake(client, tools, schema):
|
||||
params = {"name": tools[0]["name"], "arguments": ["not", "an", "object"]}
|
||||
# With a connection, when the server wants one: a refusal for lacking it would answer -32602 too
|
||||
response = rpc(client, "tools/call", with_connection(params, full_connection(schema) if schema else None))
|
||||
assert response.status_code == 200
|
||||
error = response.json().get("error")
|
||||
assert error and error.get("code") == -32602, f"expected invalid params (-32602), got: {response.text[:300]}"
|
||||
|
||||
|
||||
def test_an_invalid_request_does_not_repeat_what_it_carried():
|
||||
# No "id": the request is not valid JSON-RPC, and what it carried (a connection) must not come back.
|
||||
# It has a connection of its own: a server that answers a bad request by dropping the connection (an
|
||||
# unhandled error makes uvicorn do that) must not make the NEXT check fail with "connection reset".
|
||||
marker = f"{SENTINEL}-carried"
|
||||
try:
|
||||
response = httpx.post(
|
||||
f"{BASE_URL}/messages",
|
||||
json={"jsonrpc": "2.0", "method": "tools/list", "params": {"_meta": {CONNECTION_KEY: {"field": marker}}}},
|
||||
headers=auth_headers(),
|
||||
timeout=30.0,
|
||||
)
|
||||
except httpx.TransportError:
|
||||
return # nothing came back, so nothing was repeated
|
||||
assert marker not in response.text, "the reply to an invalid request repeated the request"
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ connection
|
||||
|
||||
|
||||
def test_the_connection_schema_is_a_json_schema_object(needs_connection):
|
||||
assert needs_connection["type"] == "object"
|
||||
properties = needs_connection["properties"]
|
||||
assert isinstance(properties, dict) and properties
|
||||
assert set(needs_connection.get("required", [])) <= set(properties), "a required field is not a property"
|
||||
|
||||
|
||||
def test_the_verify_tool_is_listed(initialize, tools, needs_connection):
|
||||
verify = (initialize.get("_meta") or {}).get(VERIFY_TOOL_KEY)
|
||||
assert verify, f"initialize does not name a verify tool in _meta[{VERIFY_TOOL_KEY!r}]"
|
||||
assert verify in [t["name"] for t in tools], f"the verify tool {verify!r} is not in tools/list"
|
||||
|
||||
|
||||
def test_a_call_with_no_connection_is_refused(client, needs_connection, probe_tool):
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
response = call(client, probe_tool, None)
|
||||
assert response.json().get("error"), (
|
||||
"a call with no connection was served. The server is using its own environment for the "
|
||||
"upstream account, so every tenant would share one. Refuse it (REQUIRE_VAULT_CONNECTION)."
|
||||
)
|
||||
|
||||
|
||||
def test_a_connection_in_the_arguments_is_not_accepted(client, needs_connection, probe_tool):
|
||||
"""The credential travels in `_meta`, which the model never sees; one in `arguments` is not one."""
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
response = call(client, probe_tool, None, arguments=full_connection(needs_connection))
|
||||
assert response.json().get("error"), "a connection passed as tool arguments was accepted"
|
||||
assert not repeated(response, needs_connection), "the reply repeats a credential that was sent as an argument"
|
||||
|
||||
|
||||
def test_a_call_with_a_connection_is_not_refused_for_lacking_one(client, needs_connection, probe_tool):
|
||||
response = call(client, probe_tool, full_connection(needs_connection))
|
||||
assert response.status_code == 200
|
||||
error = response.json().get("error") or {}
|
||||
message = str(error.get("message", "")).lower()
|
||||
assert "no connection" not in message and "missing" not in message, (
|
||||
f"a complete connection was refused as incomplete: {error}"
|
||||
)
|
||||
|
||||
|
||||
def test_an_incomplete_connection_names_what_is_missing(client, needs_connection, probe_tool):
|
||||
required = list(needs_connection.get("required", []))
|
||||
if not required:
|
||||
pytest.skip("no field is required")
|
||||
connection = full_connection(needs_connection)
|
||||
dropped = required[-1]
|
||||
connection.pop(dropped)
|
||||
if not connection:
|
||||
# The only field is required, and an empty connection counts as none. Send one that has a value
|
||||
# but not the field, which is what a mistyped field name in the credential looks like.
|
||||
connection = {"not_a_field_of_this_server": "x"}
|
||||
|
||||
response = call(client, probe_tool, connection)
|
||||
error = response.json().get("error")
|
||||
assert error, f"a connection without the required field {dropped!r} was served"
|
||||
assert dropped in str(error.get("message", "")), f"the refusal does not name the missing field {dropped!r}: {error}"
|
||||
assert not repeated(response, needs_connection), "the refusal repeats a credential value"
|
||||
|
||||
|
||||
def test_no_reply_repeats_the_credential(client, needs_connection, probe_tool, tools):
|
||||
connection = full_connection(needs_connection)
|
||||
replies = [call(client, probe_tool, connection)]
|
||||
for tool in tools[:5]:
|
||||
replies.append(call(client, tool["name"], connection, arguments={"conformance": "probe"}))
|
||||
replies.append(call(client, "no_such_tool", connection))
|
||||
for response in replies:
|
||||
assert not repeated(response, needs_connection), f"a reply repeats the credential: {response.text[:300]}"
|
||||
|
||||
|
||||
def test_a_malformed_connection_is_no_better_than_none(client, needs_connection, probe_tool):
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
for bad in ("just-a-string", ["a", "list"], 42):
|
||||
params = {"name": probe_tool, "arguments": {}, "_meta": {CONNECTION_KEY: bad}}
|
||||
body = rpc(client, "tools/call", params).json()
|
||||
assert body.get("error"), f"a connection of type {type(bad).__name__} was served"
|
||||
|
||||
|
||||
def test_resources_and_prompts_are_listed_when_advertised(client, initialize):
|
||||
capabilities = initialize.get("capabilities") or {}
|
||||
if capabilities.get("resources"):
|
||||
assert isinstance(result_of(client, "resources/list")["resources"], list)
|
||||
if capabilities.get("prompts"):
|
||||
assert isinstance(result_of(client, "prompts/list")["prompts"], list)
|
||||
83
mcp-servers/cloud-knowledge/tests/test_knowledge.py
Normal file
83
mcp-servers/cloud-knowledge/tests/test_knowledge.py
Normal file
@@ -0,0 +1,83 @@
|
||||
import asyncio
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import httpx
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
||||
import mcp_connection # noqa: E402
|
||||
import server # noqa: E402
|
||||
|
||||
|
||||
class Vendor:
|
||||
def __init__(self, tool, argument="query"):
|
||||
self.tool, self.argument, self.sent = tool, argument, []
|
||||
|
||||
def __call__(self, request):
|
||||
body = json.loads(request.content)
|
||||
self.sent.append(body)
|
||||
if body["method"] == "initialize":
|
||||
return httpx.Response(200, headers={"mcp-session-id": "s1"}, json={"result": {}})
|
||||
if body["method"] == "tools/list":
|
||||
return httpx.Response(200, json={"result": {"tools": [{"name": self.tool, "inputSchema": {
|
||||
"required": [self.argument], "properties": {self.argument: {"type": "string"}}}}]}})
|
||||
text = json.dumps({"results": [{"title": "Reliability", "contentUrl": "https://example.test/r", "content": "Guidance"}]})
|
||||
payload = json.dumps({"result": {"content": [{"type": "text", "text": text}]}})
|
||||
return httpx.Response(200, headers={"content-type": "text/event-stream"}, text=f"event: message\ndata: {payload}\n\n")
|
||||
|
||||
|
||||
def call(arguments, vendor, connection=None):
|
||||
async def run():
|
||||
client = httpx.AsyncClient(transport=httpx.MockTransport(vendor))
|
||||
original = server.get_upstream_client
|
||||
server.get_upstream_client = lambda kind, build: client
|
||||
bound = mcp_connection.bind(connection or {"google_api_key": "k"})
|
||||
try:
|
||||
return await server.cloud_search_well_architected(arguments)
|
||||
finally:
|
||||
mcp_connection.unbind(bound)
|
||||
server.get_upstream_client = original
|
||||
await client.aclose()
|
||||
|
||||
return asyncio.run(run())
|
||||
|
||||
|
||||
GOOD = {"provider": "azure", "pillar": "reliability", "topic": "landing zone"}
|
||||
|
||||
|
||||
def test_search_returns_cited_guidance():
|
||||
data = call(GOOD, Vendor("microsoft_docs_search"))["data"]
|
||||
assert data["results"][0]["url"] == "https://example.test/r" and data["evidence_ref"].startswith("sha256:")
|
||||
|
||||
|
||||
def test_query_is_built_only_from_fixed_lists():
|
||||
vendor = Vendor("microsoft_docs_search")
|
||||
call({**GOOD, "customer": "Meridian Retail", "extra": "pos-db-01"}, vendor)
|
||||
sent = json.dumps(vendor.sent)
|
||||
assert "Azure Well-Architected Framework reliability landing zone" in sent
|
||||
assert "Meridian" not in sent and "pos-db-01" not in sent
|
||||
|
||||
|
||||
def test_free_text_topic_never_leaves():
|
||||
vendor = Vendor("microsoft_docs_search")
|
||||
result = call({**GOOD, "topic": "Meridian Retail pos-db-01 outage"}, vendor)
|
||||
assert result["success"] is False and not vendor.sent
|
||||
|
||||
|
||||
def test_unknown_pillar_and_provider_are_refused():
|
||||
vendor = Vendor("microsoft_docs_search")
|
||||
assert call({**GOOD, "pillar": "x"}, vendor)["success"] is False
|
||||
assert call({**GOOD, "provider": "x"}, vendor)["success"] is False
|
||||
assert not vendor.sent
|
||||
|
||||
|
||||
def test_the_vendors_argument_name_is_read_from_the_tool():
|
||||
vendor = Vendor("aws___search_documentation", "search_phrase")
|
||||
connection = {"aws_access_key_id": "a", "aws_secret_access_key": "b"}
|
||||
call({**GOOD, "provider": "aws"}, vendor, connection)
|
||||
assert "search_phrase" in vendor.sent[-1]["params"]["arguments"]
|
||||
|
||||
|
||||
def test_a_vendor_dropping_its_tool_is_a_clean_failure():
|
||||
assert call(GOOD, Vendor("something_else"))["success"] is False
|
||||
255
mcp-servers/gcp-discovery.server.yaml
Normal file
255
mcp-servers/gcp-discovery.server.yaml
Normal file
@@ -0,0 +1,255 @@
|
||||
# Read-only discovery of a customer's Google Cloud estate. Render with scripts/render_mcp_server.py.
|
||||
# Credentials arrive per call from the Vault Service. Store them per project, never tenant-wide.
|
||||
|
||||
server_id: gcp-discovery
|
||||
name: Google Cloud Discovery
|
||||
description: Read-only discovery of a customer's Google Cloud estate - servers, workloads, Kubernetes clusters,
|
||||
networks, data stores, policies and Recommender findings - through Cloud Asset Inventory.
|
||||
version: 0.1.1
|
||||
port: 8113
|
||||
verify_tool: gcp_check_connection
|
||||
shared_code:
|
||||
- _common/tool_support.py
|
||||
- _common/gcp_support.py
|
||||
extra_requirements:
|
||||
- google-auth==2.62.0
|
||||
- requests==2.32.5
|
||||
connection_fields:
|
||||
- name: scope_root
|
||||
title: Scope root
|
||||
description: 'What may be read: organizations/<id>, folders/<id> or projects/<id>.'
|
||||
required: true
|
||||
secret: false
|
||||
- name: service_account_json
|
||||
title: Service account key
|
||||
description: The read-only service account's JSON key.
|
||||
required: true
|
||||
secret: true
|
||||
tools:
|
||||
- name: gcp_check_connection
|
||||
display_name: Check connection
|
||||
description: 'Test the stored connection: sign in and search the scope root. Returns no customer data.'
|
||||
parameters: []
|
||||
ai_implementation: |
|
||||
async def gcp_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
try:
|
||||
await _gcp_get(f"{GCP_ASSET_API}/{_gcp_scope()}:searchAllResources", {"pageSize": 1})
|
||||
except Exception as error:
|
||||
return {"ok": False, "message": _upstream_failed("gcp", error)["error"]["message"]}
|
||||
return {"ok": True, "message": "Signed in and searched the scope root."}
|
||||
- name: gcp_list_accounts
|
||||
display_name: List accounts
|
||||
description: 'List the estate structure: projects or folders under the scope root.'
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: projects, folders.'
|
||||
required: false
|
||||
- &id001
|
||||
name: page_size
|
||||
type: integer
|
||||
description: Items per page, up to 200. Default 50.
|
||||
required: false
|
||||
- &id002
|
||||
name: page_token
|
||||
type: string
|
||||
description: next_page_token from the previous reply.
|
||||
required: false
|
||||
ai_implementation: |
|
||||
async def gcp_list_accounts(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _gcp_kind("gcp_list_accounts", arguments, GCP_ACCOUNTS, "projects")
|
||||
- name: gcp_list_resources
|
||||
display_name: List resources
|
||||
description: List every resource under the scope root, or one asset type.
|
||||
parameters:
|
||||
- name: asset_type
|
||||
type: string
|
||||
description: Optional asset type, such as compute.googleapis.com/Instance.
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_list_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
asset_type = arguments.get("asset_type")
|
||||
if asset_type and not re.fullmatch(r"[a-z0-9.]+\.googleapis\.com/[A-Za-z0-9]+", str(asset_type)):
|
||||
return _refuse("invalid_argument", "asset_type must look like compute.googleapis.com/Instance")
|
||||
return await _gcp_search("gcp_list_resources", arguments, [asset_type] if asset_type else [])
|
||||
- name: gcp_query_resources
|
||||
display_name: Query resources
|
||||
description: Search resources under the scope root with Cloud Asset's query syntax.
|
||||
parameters:
|
||||
- name: query
|
||||
type: string
|
||||
description: A Cloud Asset search query, such as location:europe-west2.
|
||||
required: true
|
||||
- name: asset_type
|
||||
type: string
|
||||
description: Optional asset type.
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_query_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
query = str(arguments.get("query") or "").strip()
|
||||
if not query or len(query) > 2000:
|
||||
return _refuse("invalid_argument", "query is required, up to 2000 characters")
|
||||
asset_type = arguments.get("asset_type")
|
||||
return await _gcp_search("gcp_query_resources", arguments, [asset_type] if asset_type else [], query)
|
||||
- name: gcp_get_resource_metadata
|
||||
display_name: Get resource metadata
|
||||
description: Read-only provider metadata for one resource under the scope root.
|
||||
parameters:
|
||||
- name: resource_name
|
||||
type: string
|
||||
description: The full resource name, starting //.
|
||||
required: true
|
||||
- name: scope_entry_id
|
||||
type: string
|
||||
description: The scope entry this answers, echoed in the reply.
|
||||
required: false
|
||||
ai_implementation: |
|
||||
async def gcp_get_resource_metadata(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
name = str(arguments.get("resource_name") or "")
|
||||
if not re.fullmatch(r"//[a-z0-9.]+\.googleapis\.com/[A-Za-z0-9._/\-]+", name):
|
||||
return _refuse("invalid_argument", "resource_name must be a full resource name")
|
||||
try:
|
||||
body = await _gcp_get(f"{GCP_ASSET_API}/{_gcp_scope()}:searchAllResources", {"query": f'name="{name}"', "readMask": "*", "pageSize": 5})
|
||||
except Exception as error:
|
||||
return _upstream_failed("gcp", error)
|
||||
found = [r for r in body.get("results", []) if r.get("name") == name]
|
||||
if not found:
|
||||
return _refuse("outside_scope", "no such resource under this connection's scope")
|
||||
return _one_result("gcp", "gcp_get_resource_metadata", arguments, found[0])
|
||||
- name: gcp_list_servers
|
||||
display_name: List servers
|
||||
description: List Compute Engine instances, instance groups or disks.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: instances, instance_groups, disks.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_list_servers(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _gcp_kind("gcp_list_servers", arguments, GCP_SERVERS, "instances")
|
||||
- name: gcp_list_workloads
|
||||
display_name: List workloads
|
||||
description: List Cloud Run services, Cloud Functions or App Engine services. Environment variables are removed.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: cloud_run, cloud_functions, app_engine.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_list_workloads(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _gcp_kind("gcp_list_workloads", arguments, GCP_WORKLOADS, "cloud_run")
|
||||
- name: gcp_list_kubernetes_clusters
|
||||
display_name: List Kubernetes clusters
|
||||
description: List GKE clusters or node pools with version and networking. Stops at the cloud control plane.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: clusters, node_pools.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_list_kubernetes_clusters(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _gcp_kind("gcp_list_kubernetes_clusters", arguments, GCP_KUBERNETES, "clusters")
|
||||
- name: gcp_get_network_topology
|
||||
display_name: Get network topology
|
||||
description: List VPC networks, subnetworks, routes, firewall rules, load balancers or gateways.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: networks, subnetworks, routes, firewall_rules, load_balancers, gateways.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_get_network_topology(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _gcp_kind("gcp_get_network_topology", arguments, GCP_NETWORK, "networks")
|
||||
- name: gcp_list_data_stores
|
||||
display_name: List data stores
|
||||
description: List Cloud SQL instances, Firestore databases or Cloud Storage buckets. Metadata only.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: cloud_sql, firestore, cloud_storage.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_list_data_stores(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return await _gcp_kind("gcp_list_data_stores", arguments, GCP_DATA, "cloud_sql")
|
||||
- name: gcp_list_organization_policies
|
||||
display_name: List organization policies
|
||||
description: List Organization Policy constraints set at the scope root, or VPC Service Controls perimeters.
|
||||
parameters:
|
||||
- name: kind
|
||||
type: string
|
||||
description: 'One of: organization_policies, vpc_service_controls.'
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_list_organization_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
kind = arguments.get("kind") or "organization_policies"
|
||||
if kind == "vpc_service_controls":
|
||||
return await _gcp_kind("gcp_list_organization_policies", arguments, GCP_PERIMETERS, kind)
|
||||
if kind != "organization_policies":
|
||||
return _refuse("unknown_kind", "kind must be organization_policies or vpc_service_controls")
|
||||
return await _gcp_page("gcp_list_organization_policies", arguments, f"{GCP_ORG_POLICY_API}/{_gcp_scope()}/policies", {}, "policies")
|
||||
- name: gcp_list_resource_policies
|
||||
display_name: List resource policies
|
||||
description: List IAM policies set on resources under the scope root. People and groups are anonymised; service
|
||||
accounts stay.
|
||||
parameters:
|
||||
- name: query
|
||||
type: string
|
||||
description: Optional Cloud Asset IAM search query.
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_list_resource_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
params = {"query": arguments["query"]} if arguments.get("query") else {}
|
||||
return await _gcp_page("gcp_list_resource_policies", arguments, f"{GCP_ASSET_API}/{_gcp_scope()}:searchAllIamPolicies", params, "results")
|
||||
- name: gcp_list_recommendations
|
||||
display_name: List recommendations
|
||||
description: List Recommender findings for one project, each with a common Well-Architected pillar.
|
||||
parameters:
|
||||
- name: project_id
|
||||
type: string
|
||||
description: A project under the scope root.
|
||||
required: true
|
||||
- name: recommender
|
||||
type: string
|
||||
description: 'One of the supported recommender ids. Default: machine type.'
|
||||
required: false
|
||||
- name: location
|
||||
type: string
|
||||
description: A zone or region. Default global.
|
||||
required: false
|
||||
- *id001
|
||||
- *id002
|
||||
ai_implementation: |
|
||||
async def gcp_list_recommendations(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
||||
project_id = str(arguments.get("project_id") or "")
|
||||
location = str(arguments.get("location") or "global")
|
||||
recommender = arguments.get("recommender") or GCP_RECOMMENDERS[0]
|
||||
if recommender not in GCP_RECOMMENDERS:
|
||||
return _refuse("unknown_kind", "recommender must be one of: " + ", ".join(GCP_RECOMMENDERS))
|
||||
if not re.fullmatch(r"[a-z0-9\-]+", project_id) or not re.fullmatch(r"[a-z0-9\-]+", location):
|
||||
return _refuse("invalid_argument", "project_id and location must be plain identifiers")
|
||||
try:
|
||||
allowed = await _gcp_project_in_scope(project_id)
|
||||
except Exception as error:
|
||||
return _upstream_failed("gcp", error)
|
||||
if not allowed:
|
||||
return _refuse("outside_scope", "project_id isn't under this connection's scope")
|
||||
url = f"{GCP_RECOMMENDER_API}/projects/{project_id}/locations/{location}/recommenders/{recommender}/recommendations"
|
||||
return await _gcp_page("gcp_list_recommendations", arguments, url, {}, "recommendations", _gcp_recommendation)
|
||||
62
mcp-servers/gcp-discovery/.env.example
Normal file
62
mcp-servers/gcp-discovery/.env.example
Normal file
@@ -0,0 +1,62 @@
|
||||
# ============================================
|
||||
# Google Cloud Discovery - Environment Variables
|
||||
# ============================================
|
||||
# Generated by Agent Builder Platform
|
||||
#
|
||||
# SETUP INSTRUCTIONS:
|
||||
# 1. Copy this file to .env: cp .env.example .env
|
||||
# 2. Generate a secure API key: openssl rand -hex 32
|
||||
# 3. Update MCP_REGISTRATION_API_KEY with the generated key
|
||||
# 4. Build the image from the Dockerfile and run it where the MCP Gateway
|
||||
# can reach it (see README.md)
|
||||
#
|
||||
# MCP GATEWAY INTEGRATION:
|
||||
# When registering with the MCP Gateway, use the URL the Gateway reaches this
|
||||
# server at; for a container on the Gateway's network, its container name:
|
||||
# http://google-cloud-discovery:8113
|
||||
# ============================================
|
||||
|
||||
# Server Identity
|
||||
MCP_SERVER_NAME=Google Cloud Discovery
|
||||
MCP_SERVER_ID=gcp-discovery
|
||||
MCP_SERVER_VERSION=0.1.1
|
||||
|
||||
# Server Configuration
|
||||
MCP_SERVER_PORT=8113
|
||||
|
||||
# Logging: level (DEBUG, INFO, WARNING, ERROR) and format
|
||||
# (json = one object per line, for log stores; console = for reading by eye)
|
||||
LOG_LEVEL=INFO
|
||||
LOG_FORMAT=json
|
||||
|
||||
# ============================================
|
||||
# AUTHENTICATION (REQUIRED for production!)
|
||||
# ============================================
|
||||
# This key authenticates MCP Gateway requests to this server.
|
||||
# The Gateway stores this key and includes it in all tool/call requests.
|
||||
#
|
||||
# Generate a secure key:
|
||||
# openssl rand -hex 32
|
||||
#
|
||||
# IMPORTANT: Keep this key secret! It's stored in:
|
||||
# - This .env file (gitignored)
|
||||
# - MCP Gateway database (encrypted)
|
||||
MCP_REGISTRATION_API_KEY=<generate one: openssl rand -hex 32>
|
||||
|
||||
# Set to "false" ONLY for local development/testing
|
||||
# WARNING: Disabling auth in production is a security risk!
|
||||
REQUIRE_AUTH=true
|
||||
|
||||
# ============================================
|
||||
# CREDENTIALS FOR THE UPSTREAM (sent with each request, not set here)
|
||||
# ============================================
|
||||
# The MCP Gateway sends the tenant's credential with each call, from the Vault Service.
|
||||
# true: a call without one is refused. Set to false only for local runs, where the
|
||||
# server may use its own environment.
|
||||
REQUIRE_VAULT_CONNECTION=true
|
||||
|
||||
# ============================================
|
||||
# Add your own settings below
|
||||
# ============================================
|
||||
# Credentials for the upstream are not set here: the gateway sends them with each request.
|
||||
# EXAMPLE_SETTING=value
|
||||
15
mcp-servers/gcp-discovery/.gitignore
vendored
Normal file
15
mcp-servers/gcp-discovery/.gitignore
vendored
Normal file
@@ -0,0 +1,15 @@
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
.venv/
|
||||
venv/
|
||||
.pytest_cache/
|
||||
|
||||
# Editors
|
||||
.vscode/
|
||||
.idea/
|
||||
47
mcp-servers/gcp-discovery/Dockerfile
Normal file
47
mcp-servers/gcp-discovery/Dockerfile
Normal file
@@ -0,0 +1,47 @@
|
||||
# MCP Server Dockerfile
|
||||
# Generated by Agent Builder Platform (template 1.1.0)
|
||||
#
|
||||
# Built on the platform's MCP server base image: Chainguard Python with the
|
||||
# packages in requirements.txt already installed, a non-root user (1000) and
|
||||
# no pip. This image adds only the server's own files.
|
||||
#
|
||||
# docker build -t <server>:<version> .
|
||||
# docker build --build-arg BASE_IMAGE=<local base image> -t ... .
|
||||
ARG BASE_IMAGE=kyndryl.jfrog.io/kc-ai-agent-factory-docker-local/mcp-server-base:1.1.0
|
||||
|
||||
# Stage 1: the server's extra Python packages, if requirements.txt lists any.
|
||||
# The base image's build image (<base image>-build: the base image plus uv) installs
|
||||
# them with its vendor-install script: only the packages added go on to
|
||||
# /vendor, and one that would change a package the base image already has stops
|
||||
# the build. uv never reaches the server's image.
|
||||
FROM ${BASE_IMAGE}-build AS vendor
|
||||
COPY requirements.txt constraints.txt /tmp/
|
||||
RUN vendor-install /tmp/requirements.txt /vendor /tmp/constraints.txt
|
||||
|
||||
# Stage 2: the server: the base image, its extra packages and its files.
|
||||
FROM ${BASE_IMAGE}
|
||||
|
||||
LABEL maintainer="Agent Builder Platform"
|
||||
LABEL description="Read-only discovery of a customer's Google Cloud estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Recommender findings - through Cloud Asset Inventory."
|
||||
LABEL version="0.1.1"
|
||||
LABEL server.id="gcp-discovery"
|
||||
LABEL template.version="1.1.0"
|
||||
|
||||
COPY --from=vendor /vendor /app/vendor/
|
||||
COPY server.py mcp_connection.py /app/
|
||||
|
||||
# Environment
|
||||
# The ConfigMap's SERVER_PORT overrides this, so the container, Service and probes agree
|
||||
ENV SERVER_PORT=8113
|
||||
ENV LOG_LEVEL=INFO
|
||||
ENV LOG_FORMAT=json
|
||||
|
||||
# Expose port
|
||||
EXPOSE 8113
|
||||
|
||||
# Health check
|
||||
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
||||
CMD python -c "import os, urllib.request; urllib.request.urlopen('http://localhost:%s/health' % (os.getenv('MCP_SERVER_PORT') or os.getenv('SERVER_PORT') or '8113'))" || exit 1
|
||||
|
||||
# Run the server
|
||||
CMD ["python", "server.py"]
|
||||
198
mcp-servers/gcp-discovery/README.md
Normal file
198
mcp-servers/gcp-discovery/README.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# Google Cloud Discovery
|
||||
|
||||
Read-only discovery of a customer's Google Cloud estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Recommender findings - through Cloud Asset Inventory.
|
||||
|
||||
**Version:** 0.1.1
|
||||
**Server ID:** gcp-discovery
|
||||
**Port:** 8113
|
||||
|
||||
---
|
||||
|
||||
## 🚀 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>:8113`.
|
||||
|
||||
### 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 search the scope root. Returns no customer data.
|
||||
- **gcp_list_accounts**: List the estate structure: projects or folders under the scope root.
|
||||
- **gcp_list_resources**: List every resource under the scope root, or one asset type.
|
||||
- **gcp_query_resources**: Search resources under the scope root with Cloud Asset's query syntax.
|
||||
- **gcp_get_resource_metadata**: Read-only provider metadata for one resource under the scope root.
|
||||
- **gcp_list_servers**: List Compute Engine instances, instance groups or disks.
|
||||
- **gcp_list_workloads**: List Cloud Run services, Cloud Functions or App Engine services. Environment variables are removed.
|
||||
- **gcp_list_kubernetes_clusters**: List GKE clusters or node pools with version and networking. Stops at the cloud control plane.
|
||||
- **gcp_get_network_topology**: List VPC networks, subnetworks, routes, firewall rules, load balancers or gateways.
|
||||
- **gcp_list_data_stores**: List Cloud SQL instances, Firestore databases or Cloud Storage buckets. Metadata only.
|
||||
- **gcp_list_organization_policies**: List Organization Policy constraints set at the scope root, or VPC Service Controls perimeters.
|
||||
- **gcp_list_resource_policies**: List IAM policies set on resources under the scope root. People and groups are anonymised; service accounts stay.
|
||||
- **gcp_list_recommendations**: List Recommender findings for one project, each with a common Well-Architected pillar.
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Authentication
|
||||
|
||||
This server uses Bearer token authentication for MCP protocol messages.
|
||||
|
||||
```bash
|
||||
# Test with authentication
|
||||
curl -X POST http://localhost:8113/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:8113`)
|
||||
- **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 |
|
||||
|---|---|---|
|
||||
| `scope_root` | yes | no |
|
||||
| `service_account_json` | yes | 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:8113 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 `google-cloud-discovery/`, then add it to
|
||||
`mcp_servers_to_deploy.yaml` in that repository with the instances it should
|
||||
run on:
|
||||
|
||||
```yaml
|
||||
- name: "google-cloud-discovery"
|
||||
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:8113/health
|
||||
|
||||
# List tools
|
||||
curl -X POST http://localhost:8113/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)
|
||||
29
mcp-servers/gcp-discovery/constraints.txt
Normal file
29
mcp-servers/gcp-discovery/constraints.txt
Normal file
@@ -0,0 +1,29 @@
|
||||
# Every package installed in a generated MCP server, pinned to one exact version:
|
||||
# the ones requirements.txt names and everything they bring in. They are
|
||||
# installed in the MCP server base image (Dockerfile.base), so every server
|
||||
# built from this template gets the same versions as the platform's own
|
||||
# services.
|
||||
annotated-doc==0.0.5
|
||||
annotated-types==0.8.0
|
||||
anyio==4.15.1
|
||||
certifi==2026.10.19
|
||||
click==8.5.0
|
||||
fastapi==0.143.2
|
||||
h11==0.16.0
|
||||
httpcore==1.0.9
|
||||
httptools==0.9.0
|
||||
httpx==0.28.1
|
||||
idna==3.20
|
||||
opentelemetry-api==1.45.1
|
||||
pydantic==2.14.1
|
||||
pydantic-core==2.50.1
|
||||
python-dotenv==1.2.4
|
||||
pyyaml==6.0.3
|
||||
starlette==1.8.0
|
||||
structlog==26.1.0
|
||||
typing-extensions==4.16.0
|
||||
typing-inspection==0.4.4
|
||||
uvicorn==0.54.0
|
||||
uvloop==0.23.0
|
||||
watchfiles==1.3.0
|
||||
websockets==16.1.1
|
||||
25
mcp-servers/gcp-discovery/kubernetes/configmap.yaml
Normal file
25
mcp-servers/gcp-discovery/kubernetes/configmap.yaml
Normal file
@@ -0,0 +1,25 @@
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>-config # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
data:
|
||||
|
||||
# Read by the CI/CD pipeline: the server's name, and the port it listens on
|
||||
# (used for the container, the Service and the probes)
|
||||
MCP_SERVER_NAME: "google-cloud-discovery"
|
||||
SERVER_PORT: "8113"
|
||||
|
||||
# One JSON object per line; LOG_FORMAT=console prints readable lines
|
||||
LOG_LEVEL: "INFO"
|
||||
LOG_FORMAT: "json"
|
||||
|
||||
# Leave on. The Gateway authenticates to this server with a bearer token, and
|
||||
# turning this off makes every tool callable by anything that can reach the
|
||||
# pod inside the cluster.
|
||||
REQUIRE_AUTH: "true"
|
||||
|
||||
# Refuse a call that arrives without the tenant's credential from the Vault Service
|
||||
REQUIRE_VAULT_CONNECTION: "true"
|
||||
|
||||
# Add your own settings here
|
||||
# EXAMPLE_SETTING: "value"
|
||||
71
mcp-servers/gcp-discovery/kubernetes/deployment.yaml
Normal file
71
mcp-servers/gcp-discovery/kubernetes/deployment.yaml
Normal file
@@ -0,0 +1,71 @@
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
imagePullSecrets:
|
||||
- name: jfrog-secret
|
||||
containers:
|
||||
- name: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
image: <placeholder_for_image> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
imagePullPolicy: Always
|
||||
ports:
|
||||
- containerPort: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
name: http
|
||||
# Load all environment variables from ConfigMap
|
||||
envFrom:
|
||||
- secretRef:
|
||||
name: <placeholder_for_mcp_server_name>-secrets # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
optional: true # Won't fail if secret doesn't exist
|
||||
- secretRef:
|
||||
name: <placeholder_for_mcp_server_name>-dotenv-secrets # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
optional: true # Won't fail if secret doesn't exist
|
||||
- configMapRef:
|
||||
name: <placeholder_for_mcp_server_name>-config # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
# The registration key and server id are generated by the CI/CD pipeline;
|
||||
# the server needs the key to accept the Gateway's calls
|
||||
env:
|
||||
- name: MCP_REGISTRATION_API_KEY
|
||||
value: "<placeholder_for_registration_api_key>" # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
- name: MCP_SERVER_ID
|
||||
value: "<placeholder_for_server_id>" # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
resources:
|
||||
requests:
|
||||
memory: "128Mi"
|
||||
cpu: "10m"
|
||||
limits:
|
||||
memory: "1024Mi"
|
||||
cpu: "1000m"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
initialDelaySeconds: 30 # Wait X seconds before first check
|
||||
periodSeconds: 15 # Check every X seconds
|
||||
timeoutSeconds: 10 # Each check can take up to X seconds to respond
|
||||
failureThreshold: 5 # Allow X consecutive failures before marking unhealthy
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
initialDelaySeconds: 30 # Wait X seconds before first check
|
||||
periodSeconds: 15 # Check every X seconds
|
||||
timeoutSeconds: 10 # Each check can take up to X seconds to respond
|
||||
failureThreshold: 5 # Allow X consecutive failures before marking unhealthy
|
||||
|
||||
# volumes:
|
||||
# - name: execution-storage
|
||||
# persistentVolumeClaim:
|
||||
# claimName: execution-storage-pvc # Same PVC name as core-components
|
||||
20
mcp-servers/gcp-discovery/kubernetes/kustomization.yaml
Normal file
20
mcp-servers/gcp-discovery/kubernetes/kustomization.yaml
Normal file
@@ -0,0 +1,20 @@
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
|
||||
resources:
|
||||
- namespace.yaml
|
||||
- deployment.yaml
|
||||
- service.yaml
|
||||
- configmap.yaml
|
||||
- secretnames.yaml
|
||||
|
||||
# Optionally add common labels
|
||||
|
||||
# Namespace for all resources
|
||||
namespace: mcp-servers
|
||||
labels:
|
||||
- includeSelectors: true
|
||||
pairs:
|
||||
app: <placeholder_for_mcp_server_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
environment: production
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
7
mcp-servers/gcp-discovery/kubernetes/namespace.yaml
Normal file
7
mcp-servers/gcp-discovery/kubernetes/namespace.yaml
Normal file
@@ -0,0 +1,7 @@
|
||||
# Do not modify this file, otherwise CI/CD pipeline will fail
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: mcp-servers
|
||||
labels:
|
||||
name: mcp-servers
|
||||
18
mcp-servers/gcp-discovery/kubernetes/secretnames.yaml
Normal file
18
mcp-servers/gcp-discovery/kubernetes/secretnames.yaml
Normal file
@@ -0,0 +1,18 @@
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>-secrets
|
||||
type: Opaque
|
||||
data:
|
||||
# Base64 encoded values (NOT RECOMMENDED for sensitive data)
|
||||
# To encode: echo -n 'your-secret-value' | base64
|
||||
# Example: api-key: eW91ci1hcGkta2V5LXZhbHVl
|
||||
|
||||
stringData:
|
||||
# Plain text values saved on GitHub Secrets (RECOMMENDED)
|
||||
# Example:
|
||||
#
|
||||
# DB_PASSWORD: ${DB_PASSWORD_GITHUB_SECRET}
|
||||
# ANOTHER_SECRET: ${ANOTHER_GITHUB_SECRET}
|
||||
#
|
||||
# ${DB_PASSWORD_GITHUB_SECRET} and ${ANOTHER_GITHUB_SECRET} must exist as GitHub Secrets
|
||||
33
mcp-servers/gcp-discovery/kubernetes/service.yaml
Normal file
33
mcp-servers/gcp-discovery/kubernetes/service.yaml
Normal file
@@ -0,0 +1,33 @@
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: <placeholder_for_mcp_server_name>
|
||||
labels:
|
||||
app: <placeholder_for_mcp_server_name>
|
||||
repo: <placeholder_for_repo_name> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
spec:
|
||||
type: ClusterIP
|
||||
ports:
|
||||
- port: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
targetPort: <placeholder_for_port> # Do not modify, this will be replaced during deployment by the CI/CD pipeline
|
||||
protocol: TCP
|
||||
name: http
|
||||
selector:
|
||||
app: <placeholder_for_mcp_server_name>
|
||||
---
|
||||
# Optional: LoadBalancer service for external access
|
||||
# apiVersion: v1
|
||||
# kind: Service
|
||||
# metadata:
|
||||
# name: <placeholder_for_mcp_server_name>-external
|
||||
# labels:
|
||||
# app: <placeholder_for_mcp_server_name>
|
||||
# spec:
|
||||
# type: LoadBalancer
|
||||
# ports:
|
||||
# - port: 80
|
||||
# targetPort: 8080
|
||||
# protocol: TCP
|
||||
# name: http
|
||||
# selector:
|
||||
# app: <placeholder_for_mcp_server_name>
|
||||
256
mcp-servers/gcp-discovery/mcp_connection.py
Normal file
256
mcp-servers/gcp-discovery/mcp_connection.py
Normal file
@@ -0,0 +1,256 @@
|
||||
"""The connection a request carries: which upstream account this call is for.
|
||||
|
||||
An MCP server that talks to a third-party system needs that system's address and credentials. Taking
|
||||
them from environment variables makes one process serve one account for ever. Here the MCP Gateway
|
||||
sends them with each call, from the Vault Service, in MCP's own `_meta` field, under our vendor prefix:
|
||||
|
||||
initialize result _meta["com.kyndryl.mcp/connection-schema"] what this server needs (JSON Schema)
|
||||
_meta["com.kyndryl.mcp/verify-tool"] the tool that tests a connection
|
||||
tools/call, resources/read, prompts/get
|
||||
params._meta["com.kyndryl.mcp/connection"] the values, matching that schema
|
||||
|
||||
`_meta` is where the specification tells implementations to put their own data, so a client that does
|
||||
not know these keys ignores them. The values never travel in `arguments`, which is what the model
|
||||
writes and reads, so a credential cannot enter the model's context.
|
||||
|
||||
The connection is bound for the life of one request and read with `active()`. It is None when the caller
|
||||
sent nothing; whether the server may then use its own environment is decided in server.py
|
||||
(REQUIRE_VAULT_CONNECTION, which is on by default).
|
||||
|
||||
WHAT IS STANDARD AND WHAT IS OURS
|
||||
---------------------------------
|
||||
The mechanism is standard. `_meta` is the specification's sanctioned place for implementation-specific
|
||||
data, with formal key-naming rules (2026-07-28, "General fields / _meta"):
|
||||
|
||||
Prefix ... SHOULD use reverse DNS notation. Any prefix where the second label is
|
||||
`modelcontextprotocol` or `mcp` is reserved for MCP use ... third-party extensions use their own
|
||||
vendor prefix.
|
||||
|
||||
`com.kyndryl.mcp/` satisfies that: the second label is `kyndryl`, so it is a legitimate vendor prefix and
|
||||
not reserved. A client that does not recognise our keys ignores them, which is exactly what `_meta` is for.
|
||||
The value carried is a *separate* upstream credential, never the caller's own token (the specification
|
||||
says a server MUST NOT pass through the token it received from its client).
|
||||
|
||||
Only the three key names and the shape of their payloads are ours. When SEP-2127 (MCP Server Card) lands,
|
||||
the schema is what moves onto the card, and the key names are the only thing that changes.
|
||||
|
||||
The third key, VERIFY_TOOL_KEY, adds very little. Checking a credential is a plain `tools/call` against an
|
||||
ordinary tool that appears in `tools/list` like any other: no new method, no new transport. The only
|
||||
question that needed answering is WHICH tool, and the alternative was for the gateway to guess by name. A
|
||||
server that advertises nothing here is simply not verifiable.
|
||||
|
||||
STATELESSNESS
|
||||
-------------
|
||||
The 2026-07-28 specification made MCP explicitly stateless: "Servers MUST NOT rely on prior requests over
|
||||
the same connection to establish context ... Every request supplies this metadata in its _meta field."
|
||||
A module-level connection built once at import is exactly the state the specification tells servers not to
|
||||
keep. Binding the connection per request is therefore not only what multi-tenancy needs, it is what the
|
||||
protocol asks for.
|
||||
|
||||
HOW IT IS USED (server.py does all of this; a tool only calls get_connection())
|
||||
------------------------------------------------------------------------------
|
||||
import mcp_connection
|
||||
|
||||
# advertise, in the initialize result
|
||||
result["_meta"] = mcp_connection.schema_meta(CONNECTION_SCHEMA, verify_tool="verify_connection")
|
||||
|
||||
# bind, for the life of one request
|
||||
token = mcp_connection.bind(mcp_connection.from_params(request.params))
|
||||
try:
|
||||
... # mcp_connection.active() anywhere below
|
||||
finally:
|
||||
mcp_connection.unbind(token)
|
||||
|
||||
LOGS AND ERROR MESSAGES
|
||||
-----------------------
|
||||
`scrub()` is applied to every log line, and to the `error` text of a failed tool call, so the connection's
|
||||
values and credential-looking URL parameters (`?key=...`) never leave the process. `redact()` does the
|
||||
connection values alone. Neither is applied to a successful result: a presigned URL a tool returns on
|
||||
purpose must survive.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextvars
|
||||
import hashlib
|
||||
import hmac
|
||||
import json
|
||||
import re
|
||||
import secrets
|
||||
from typing import Any, Callable, Dict, List, Optional
|
||||
|
||||
VENDOR = "com.kyndryl.mcp"
|
||||
SCHEMA_KEY = f"{VENDOR}/connection-schema"
|
||||
CONNECTION_KEY = f"{VENDOR}/connection"
|
||||
VERIFY_TOOL_KEY = f"{VENDOR}/verify-tool"
|
||||
|
||||
_active: contextvars.ContextVar[Optional[Dict[str, Any]]] = contextvars.ContextVar(
|
||||
"mcp_connection", default=None
|
||||
)
|
||||
|
||||
# Per process, so a fingerprint in a log cannot be checked against a guessed credential offline
|
||||
_FINGERPRINT_KEY = secrets.token_bytes(32)
|
||||
|
||||
|
||||
def schema_meta(schema: Dict[str, Any], verify_tool: Optional[str] = None) -> Dict[str, Any]:
|
||||
"""The `_meta` object that advertises `schema` on an initialize result."""
|
||||
meta: Dict[str, Any] = {SCHEMA_KEY: schema}
|
||||
if verify_tool:
|
||||
meta[VERIFY_TOOL_KEY] = verify_tool
|
||||
return meta
|
||||
|
||||
|
||||
def verify_tool_from_initialize(result: Optional[Dict[str, Any]]) -> Optional[str]:
|
||||
"""The verify tool an initialize result advertises, or None.
|
||||
|
||||
The reader half of schema_meta, here rather than in the gateway so the two ends of the key cannot
|
||||
drift apart.
|
||||
"""
|
||||
if not isinstance(result, dict):
|
||||
return None
|
||||
meta = result.get("_meta")
|
||||
if not isinstance(meta, dict):
|
||||
return None
|
||||
name = meta.get(VERIFY_TOOL_KEY)
|
||||
return name if isinstance(name, str) and name.strip() else None
|
||||
|
||||
|
||||
def from_params(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
|
||||
"""The connection in a request's `params._meta`, or None.
|
||||
|
||||
Anything that is not an object counts as absent: a malformed connection must not be more
|
||||
powerful than none at all.
|
||||
"""
|
||||
if not isinstance(params, dict):
|
||||
return None
|
||||
meta = params.get("_meta")
|
||||
if not isinstance(meta, dict):
|
||||
return None
|
||||
profile = meta.get(CONNECTION_KEY)
|
||||
return profile if isinstance(profile, dict) and profile else None
|
||||
|
||||
|
||||
def bind(profile: Optional[Dict[str, Any]]) -> contextvars.Token:
|
||||
"""Make `profile` the connection for this request."""
|
||||
return _active.set(profile)
|
||||
|
||||
|
||||
def unbind(token: contextvars.Token) -> None:
|
||||
try:
|
||||
_active.reset(token)
|
||||
except ValueError:
|
||||
_active.set(None)
|
||||
|
||||
|
||||
def active() -> Optional[Dict[str, Any]]:
|
||||
"""The connection for this request, or None."""
|
||||
return _active.get()
|
||||
|
||||
|
||||
def fingerprint(profile: Optional[Dict[str, Any]]) -> str:
|
||||
"""A short id for a connection, safe to log and to cache on; the credential never is the key."""
|
||||
if not profile:
|
||||
return "env"
|
||||
canonical = json.dumps(profile, sort_keys=True, separators=(",", ":"), default=str)
|
||||
return hmac.new(_FINGERPRINT_KEY, canonical.encode("utf-8"), hashlib.sha256).hexdigest()[:16]
|
||||
|
||||
|
||||
def redact(text: Any) -> str:
|
||||
"""`text` with every value of this request's connection replaced, for logs and error replies.
|
||||
|
||||
A tool can put a credential in an exception message without meaning to. Values shorter than four
|
||||
characters are left alone: replacing them would garble ordinary text.
|
||||
"""
|
||||
result = str(text)
|
||||
values = [v for v in (active() or {}).values() if isinstance(v, str) and len(v) >= 4]
|
||||
for value in sorted(values, key=len, reverse=True):
|
||||
result = result.replace(value, "[redacted]")
|
||||
return result
|
||||
|
||||
|
||||
# Query parameters that carry a credential in the URL of an upstream request
|
||||
_URL_CREDENTIAL = re.compile(
|
||||
r"([?&;](?:api[_-]?key|apikey|key|token|access[_-]?token|auth|secret|password|passwd|"
|
||||
r"client[_-]?secret|appid|app[_-]?id|sig|signature)=)[^&\s\"'#<>]+",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
|
||||
def scrub(value: Any, _depth: int = 0) -> Any:
|
||||
"""`value` with credentials taken out, for anything that is logged or sent back to a caller.
|
||||
|
||||
Strings lose the request's connection values and the value of any credential query parameter in a
|
||||
URL (`?key=...`); dicts, lists and tuples are scrubbed inside. Anything else is returned as it is.
|
||||
Not for tool results in general: a presigned URL a tool returns on purpose would be damaged.
|
||||
"""
|
||||
if isinstance(value, str):
|
||||
return _URL_CREDENTIAL.sub(r"\1[redacted]", redact(value))
|
||||
if _depth > 5:
|
||||
return value
|
||||
if isinstance(value, dict):
|
||||
return {k: scrub(v, _depth + 1) for k, v in value.items()}
|
||||
if isinstance(value, (list, tuple)):
|
||||
return type(value)(scrub(v, _depth + 1) for v in value)
|
||||
return value
|
||||
|
||||
|
||||
def missing_fields(profile: Optional[Dict[str, Any]], schema: Dict[str, Any]) -> List[str]:
|
||||
"""The required fields of `schema` that `profile` does not supply."""
|
||||
if not profile:
|
||||
return []
|
||||
required = schema.get("required") or []
|
||||
return [name for name in required if not str(profile.get(name) or "").strip()]
|
||||
|
||||
|
||||
def install_invalid_request_handler(app: Any, on_invalid: Optional[Callable[[str], None]] = None) -> None:
|
||||
"""Answer a request that is not valid JSON-RPC with a JSON-RPC error that does not repeat the request.
|
||||
|
||||
FastAPI's own answer (HTTP 422) repeats the request body under "input". The body is where the gateway puts
|
||||
the tenant's connection, so a request that is merely malformed (no "id", say) would get the credential back
|
||||
in the reply, and in the log of anything that records replies. The status stays 422; the body is a JSON-RPC
|
||||
error (-32600) that names only the fields at fault. `on_invalid`, if given, is called with that text, already
|
||||
reduced to harmless characters, so the caller can log it in its own style.
|
||||
|
||||
Call it once, right after `app = FastAPI(...)`. FastAPI is imported here, not at module level, so the rest of
|
||||
this module stays importable without it.
|
||||
"""
|
||||
from fastapi.exceptions import RequestValidationError
|
||||
from fastapi.responses import JSONResponse
|
||||
|
||||
@app.exception_handler(RequestValidationError)
|
||||
async def invalid_request(request, exc):
|
||||
names = {
|
||||
"body" if error.get("type") == "json_invalid" else ".".join(str(p) for p in error.get("loc", ())[1:]) or "body"
|
||||
for error in exc.errors()
|
||||
}
|
||||
fields = re.sub(r"[^\w.\-, ]", "?", ", ".join(sorted(names)))[:200]
|
||||
if on_invalid is not None:
|
||||
on_invalid(fields)
|
||||
return JSONResponse(
|
||||
status_code=422,
|
||||
content={
|
||||
"jsonrpc": "2.0",
|
||||
"id": None,
|
||||
"result": None,
|
||||
"error": {"code": -32600, "message": "Invalid request: check " + fields},
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"install_invalid_request_handler",
|
||||
"VENDOR",
|
||||
"SCHEMA_KEY",
|
||||
"CONNECTION_KEY",
|
||||
"VERIFY_TOOL_KEY",
|
||||
"schema_meta",
|
||||
"verify_tool_from_initialize",
|
||||
"from_params",
|
||||
"bind",
|
||||
"unbind",
|
||||
"active",
|
||||
"fingerprint",
|
||||
"redact",
|
||||
"scrub",
|
||||
"missing_fields",
|
||||
]
|
||||
43
mcp-servers/gcp-discovery/requirements.txt
Normal file
43
mcp-servers/gcp-discovery/requirements.txt
Normal file
@@ -0,0 +1,43 @@
|
||||
# MCP Server Dependencies
|
||||
# Generated by Agent Builder Platform
|
||||
|
||||
# Each dependency is pinned to one exact version, and constraints.txt pins everything they bring
|
||||
# in, so two builds of the same server get the same packages -- the same versions as the
|
||||
# platform's own services. The packages below are already installed in the MCP server base
|
||||
# image the Dockerfile builds on; a package added to this file is installed on top of them at
|
||||
# build time. Changing the version of one the base has stops the build: the base image moves
|
||||
# those, with the template.
|
||||
|
||||
# Core Framework
|
||||
# FastAPI - Modern web framework for MCP server
|
||||
fastapi==0.143.2
|
||||
|
||||
# ASGI Server
|
||||
# Uvicorn - Lightning-fast ASGI server
|
||||
uvicorn[standard]==0.54.0
|
||||
|
||||
# Data Validation
|
||||
# Pydantic - Data validation using Python type hints
|
||||
pydantic==2.14.1
|
||||
|
||||
# HTTP Client
|
||||
# HTTPX - Async HTTP client for API calls
|
||||
httpx==0.28.1
|
||||
|
||||
# Environment Variables
|
||||
# python-dotenv - Load environment from .env files
|
||||
python-dotenv==1.2.4
|
||||
|
||||
# Structured Logging
|
||||
# structlog - JSON log lines (see LOG_FORMAT in server.py)
|
||||
structlog==26.1.0
|
||||
|
||||
# Optional: Add your custom dependencies below
|
||||
# requests>=2.31.0
|
||||
# aiofiles>=23.2.1
|
||||
# sqlalchemy>=2.0.0
|
||||
# redis>=5.0.0
|
||||
|
||||
# Added by this server's definition
|
||||
google-auth==2.62.0
|
||||
requests==2.32.5
|
||||
1293
mcp-servers/gcp-discovery/server.py
Normal file
1293
mcp-servers/gcp-discovery/server.py
Normal file
File diff suppressed because it is too large
Load Diff
360
mcp-servers/gcp-discovery/tests/test_conformance.py
Normal file
360
mcp-servers/gcp-discovery/tests/test_conformance.py
Normal file
@@ -0,0 +1,360 @@
|
||||
"""Conformance checks for an MCP server that takes its upstream credentials from the MCP Gateway.
|
||||
|
||||
Run these against a running server before you push it. They need only `pytest` and `httpx`, import
|
||||
nothing from the server and talk to it over HTTP, so they work on a server from the MCP Server
|
||||
Builder and on one written by hand.
|
||||
|
||||
pip install pytest httpx
|
||||
MCP_SERVER_URL=http://localhost:8100 MCP_REGISTRATION_API_KEY=<the server's key> pytest tests/ -v
|
||||
|
||||
What is checked, and why:
|
||||
|
||||
Protocol the server answers /health, refuses callers without its key, and speaks JSON-RPC
|
||||
correctly (initialize, tools/list, ids echoed, errors as errors).
|
||||
Connection a server that needs an upstream account says so in its initialize result
|
||||
(`_meta["com.kyndryl.mcp/connection-schema"]`) and takes the account from each
|
||||
request (`params._meta["com.kyndryl.mcp/connection"]`), not from its own environment.
|
||||
Such a server refuses a call that carries none (fail closed), reports which required
|
||||
field is missing, takes nothing from `arguments`, and never repeats a credential in a
|
||||
reply (the values of fields marked `writeOnly`; every value if none is marked). A server that needs no account skips these checks.
|
||||
|
||||
Settings (environment variables):
|
||||
|
||||
MCP_SERVER_URL default http://localhost:8100
|
||||
MCP_REGISTRATION_API_KEY the key the server was started with (required unless the
|
||||
server has authentication switched off)
|
||||
CONFORMANCE_EXPECT_FAIL_CLOSED default true. Set false only for a server you run locally
|
||||
with REQUIRE_VAULT_CONNECTION=false, so that checks which
|
||||
need a refusal are skipped rather than failed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import secrets
|
||||
import uuid
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
VENDOR = "com.kyndryl.mcp"
|
||||
SCHEMA_KEY = f"{VENDOR}/connection-schema"
|
||||
VERIFY_TOOL_KEY = f"{VENDOR}/verify-tool"
|
||||
CONNECTION_KEY = f"{VENDOR}/connection"
|
||||
|
||||
BASE_URL = os.getenv("MCP_SERVER_URL", "http://localhost:8100").rstrip("/")
|
||||
API_KEY = os.getenv("MCP_REGISTRATION_API_KEY", "")
|
||||
EXPECT_FAIL_CLOSED = os.getenv("CONFORMANCE_EXPECT_FAIL_CLOSED", "true").strip().lower() != "false"
|
||||
|
||||
# A value no server could contain by accident, so finding it in a reply means the server repeated it.
|
||||
SENTINEL = f"sentinel-{secrets.token_hex(6)}"
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ helpers
|
||||
|
||||
|
||||
def auth_headers(key: Optional[str] = None) -> Dict[str, str]:
|
||||
key = API_KEY if key is None else key
|
||||
return {"Authorization": f"Bearer {key}"} if key else {}
|
||||
|
||||
|
||||
def rpc(
|
||||
client: httpx.Client,
|
||||
method: str,
|
||||
params: Optional[Dict[str, Any]] = None,
|
||||
*,
|
||||
request_id: Any = "1",
|
||||
headers: Optional[Dict[str, str]] = None,
|
||||
) -> httpx.Response:
|
||||
return client.post(
|
||||
"/messages",
|
||||
json={"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}},
|
||||
headers=auth_headers() if headers is None else headers,
|
||||
)
|
||||
|
||||
|
||||
def result_of(client: httpx.Client, method: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
||||
response = rpc(client, method, params)
|
||||
assert response.status_code == 200, f"{method} answered HTTP {response.status_code}: {response.text[:300]}"
|
||||
body = response.json()
|
||||
assert not body.get("error"), f"{method} returned an error: {body['error']}"
|
||||
return body["result"]
|
||||
|
||||
|
||||
def with_connection(params: Dict[str, Any], connection: Optional[Dict[str, Any]]) -> Dict[str, Any]:
|
||||
if connection is None:
|
||||
return params
|
||||
return {**params, "_meta": {CONNECTION_KEY: connection}}
|
||||
|
||||
|
||||
def value_for(name: str, spec: Dict[str, Any]) -> Any:
|
||||
"""A value of the right shape for a connection field, carrying the sentinel."""
|
||||
kind = spec.get("type", "string")
|
||||
if kind == "string" and spec.get("format") == "uri":
|
||||
return f"https://{SENTINEL}.invalid"
|
||||
if kind == "integer":
|
||||
return 12345
|
||||
if kind == "boolean":
|
||||
return True
|
||||
return f"{SENTINEL}-{name}"
|
||||
|
||||
|
||||
def full_connection(schema: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return {name: value_for(name, spec) for name, spec in (schema.get("properties") or {}).items()}
|
||||
|
||||
|
||||
def secret_values(schema: Dict[str, Any]) -> List[str]:
|
||||
"""The sent values that must never come back: those of fields marked secret (`writeOnly`).
|
||||
|
||||
A tool may repeat a base URL or a region. If the server marks no field secret, every value is
|
||||
treated as one, because then nothing says which are safe to repeat.
|
||||
"""
|
||||
connection = full_connection(schema)
|
||||
properties = schema.get("properties") or {}
|
||||
marked = [n for n, spec in properties.items() if spec.get("writeOnly")]
|
||||
return [str(connection[n]) for n in (marked or list(properties))]
|
||||
|
||||
|
||||
def repeated(response: httpx.Response, schema: Dict[str, Any]) -> List[str]:
|
||||
return [v for v in secret_values(schema) if v in response.text]
|
||||
|
||||
|
||||
def _string_values(node: Any) -> List[str]:
|
||||
"""Every string anywhere in a JSON value."""
|
||||
if isinstance(node, str):
|
||||
return [node]
|
||||
if isinstance(node, dict):
|
||||
return [v for item in node.values() for v in _string_values(item)]
|
||||
if isinstance(node, list):
|
||||
return [v for item in node for v in _string_values(item)]
|
||||
return []
|
||||
|
||||
|
||||
def call(client: httpx.Client, tool: str, connection: Optional[Dict[str, Any]], arguments: Optional[Dict] = None):
|
||||
return rpc(client, "tools/call", with_connection({"name": tool, "arguments": arguments or {}}, connection))
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ fixtures
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def client():
|
||||
with httpx.Client(base_url=BASE_URL, timeout=30.0) as session:
|
||||
try:
|
||||
session.get("/health")
|
||||
except httpx.HTTPError as error:
|
||||
pytest.exit(f"Cannot reach the server at {BASE_URL}: {error}. Start it, or set MCP_SERVER_URL.", 2)
|
||||
yield session
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def initialize(client) -> Dict[str, Any]:
|
||||
return result_of(client, "initialize", {"protocolVersion": "1.0.0", "clientInfo": {"name": "conformance"}})
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def tools(client) -> List[Dict[str, Any]]:
|
||||
return result_of(client, "tools/list")["tools"]
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def schema(initialize) -> Optional[Dict[str, Any]]:
|
||||
return (initialize.get("_meta") or {}).get(SCHEMA_KEY)
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def needs_connection(schema) -> Dict[str, Any]:
|
||||
if not schema or not schema.get("properties"):
|
||||
pytest.skip("the server advertises no connection fields, so it takes no per-request credentials")
|
||||
return schema
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def probe_tool(initialize, tools) -> str:
|
||||
"""The tool to call in the connection checks: the verify tool when there is one."""
|
||||
verify = (initialize.get("_meta") or {}).get(VERIFY_TOOL_KEY)
|
||||
if verify:
|
||||
return verify
|
||||
assert tools, "the server lists no tools to call"
|
||||
return tools[0]["name"]
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ protocol
|
||||
|
||||
|
||||
def test_health_answers(client):
|
||||
assert client.get("/health").status_code == 200
|
||||
|
||||
|
||||
def test_the_public_auth_endpoint_reveals_no_key(client):
|
||||
response = client.get("/.well-known/mcp-auth")
|
||||
if response.status_code == 404:
|
||||
pytest.skip("the server has no /.well-known/mcp-auth endpoint")
|
||||
assert response.status_code == 200
|
||||
if API_KEY:
|
||||
# A value that equals the key is always a leak. A short key can also appear inside ordinary words
|
||||
# ("nc" in "auth_required"), so searching the text for it is only meaningful for a real-length key.
|
||||
assert API_KEY not in _string_values(response.json()), "/.well-known/mcp-auth returns the server's key"
|
||||
if len(API_KEY) >= 12:
|
||||
assert API_KEY not in response.text, "/.well-known/mcp-auth returns the server's key"
|
||||
|
||||
|
||||
def test_a_call_without_the_servers_key_is_refused(client):
|
||||
response = rpc(client, "tools/list", headers={})
|
||||
assert response.status_code in (401, 403), f"answered HTTP {response.status_code} to a caller with no key"
|
||||
|
||||
|
||||
def test_a_call_with_the_wrong_key_is_refused(client):
|
||||
response = rpc(client, "tools/list", headers=auth_headers("not-the-key-" + uuid.uuid4().hex))
|
||||
assert response.status_code in (401, 403), f"answered HTTP {response.status_code} to a caller with the wrong key"
|
||||
|
||||
|
||||
def test_initialize_describes_the_server(initialize):
|
||||
assert initialize["serverInfo"]["name"]
|
||||
assert isinstance(initialize.get("capabilities"), dict)
|
||||
|
||||
|
||||
def test_tools_have_a_name_a_description_and_an_object_schema(tools):
|
||||
assert isinstance(tools, list)
|
||||
names = [t["name"] for t in tools]
|
||||
assert len(names) == len(set(names)), "two tools share a name"
|
||||
for tool in tools:
|
||||
assert tool["name"] and tool.get("description"), f"tool {tool.get('name')!r} lacks a name or description"
|
||||
assert tool["inputSchema"]["type"] == "object", f"{tool['name']} has no object inputSchema"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("request_id", ["conformance-1", 7])
|
||||
def test_the_reply_echoes_the_request_id(client, request_id):
|
||||
response = rpc(client, "tools/list", request_id=request_id)
|
||||
assert response.status_code == 200
|
||||
assert response.json()["id"] == request_id
|
||||
|
||||
|
||||
def test_an_unknown_method_is_an_error_not_a_crash(client):
|
||||
response = rpc(client, "no/such/method")
|
||||
assert response.status_code == 200
|
||||
assert response.json().get("error"), "an unknown method returned no error"
|
||||
|
||||
|
||||
def test_an_unknown_tool_is_an_error_not_a_crash(client):
|
||||
response = rpc(client, "tools/call", {"name": f"no_such_tool_{uuid.uuid4().hex[:8]}", "arguments": {}})
|
||||
assert response.status_code == 200
|
||||
assert response.json().get("error"), "an unknown tool returned no error"
|
||||
|
||||
|
||||
def test_arguments_that_are_not_an_object_are_the_callers_mistake(client, tools, schema):
|
||||
params = {"name": tools[0]["name"], "arguments": ["not", "an", "object"]}
|
||||
# With a connection, when the server wants one: a refusal for lacking it would answer -32602 too
|
||||
response = rpc(client, "tools/call", with_connection(params, full_connection(schema) if schema else None))
|
||||
assert response.status_code == 200
|
||||
error = response.json().get("error")
|
||||
assert error and error.get("code") == -32602, f"expected invalid params (-32602), got: {response.text[:300]}"
|
||||
|
||||
|
||||
def test_an_invalid_request_does_not_repeat_what_it_carried():
|
||||
# No "id": the request is not valid JSON-RPC, and what it carried (a connection) must not come back.
|
||||
# It has a connection of its own: a server that answers a bad request by dropping the connection (an
|
||||
# unhandled error makes uvicorn do that) must not make the NEXT check fail with "connection reset".
|
||||
marker = f"{SENTINEL}-carried"
|
||||
try:
|
||||
response = httpx.post(
|
||||
f"{BASE_URL}/messages",
|
||||
json={"jsonrpc": "2.0", "method": "tools/list", "params": {"_meta": {CONNECTION_KEY: {"field": marker}}}},
|
||||
headers=auth_headers(),
|
||||
timeout=30.0,
|
||||
)
|
||||
except httpx.TransportError:
|
||||
return # nothing came back, so nothing was repeated
|
||||
assert marker not in response.text, "the reply to an invalid request repeated the request"
|
||||
|
||||
|
||||
# ------------------------------------------------------------------------------------ connection
|
||||
|
||||
|
||||
def test_the_connection_schema_is_a_json_schema_object(needs_connection):
|
||||
assert needs_connection["type"] == "object"
|
||||
properties = needs_connection["properties"]
|
||||
assert isinstance(properties, dict) and properties
|
||||
assert set(needs_connection.get("required", [])) <= set(properties), "a required field is not a property"
|
||||
|
||||
|
||||
def test_the_verify_tool_is_listed(initialize, tools, needs_connection):
|
||||
verify = (initialize.get("_meta") or {}).get(VERIFY_TOOL_KEY)
|
||||
assert verify, f"initialize does not name a verify tool in _meta[{VERIFY_TOOL_KEY!r}]"
|
||||
assert verify in [t["name"] for t in tools], f"the verify tool {verify!r} is not in tools/list"
|
||||
|
||||
|
||||
def test_a_call_with_no_connection_is_refused(client, needs_connection, probe_tool):
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
response = call(client, probe_tool, None)
|
||||
assert response.json().get("error"), (
|
||||
"a call with no connection was served. The server is using its own environment for the "
|
||||
"upstream account, so every tenant would share one. Refuse it (REQUIRE_VAULT_CONNECTION)."
|
||||
)
|
||||
|
||||
|
||||
def test_a_connection_in_the_arguments_is_not_accepted(client, needs_connection, probe_tool):
|
||||
"""The credential travels in `_meta`, which the model never sees; one in `arguments` is not one."""
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
response = call(client, probe_tool, None, arguments=full_connection(needs_connection))
|
||||
assert response.json().get("error"), "a connection passed as tool arguments was accepted"
|
||||
assert not repeated(response, needs_connection), "the reply repeats a credential that was sent as an argument"
|
||||
|
||||
|
||||
def test_a_call_with_a_connection_is_not_refused_for_lacking_one(client, needs_connection, probe_tool):
|
||||
response = call(client, probe_tool, full_connection(needs_connection))
|
||||
assert response.status_code == 200
|
||||
error = response.json().get("error") or {}
|
||||
message = str(error.get("message", "")).lower()
|
||||
assert "no connection" not in message and "missing" not in message, (
|
||||
f"a complete connection was refused as incomplete: {error}"
|
||||
)
|
||||
|
||||
|
||||
def test_an_incomplete_connection_names_what_is_missing(client, needs_connection, probe_tool):
|
||||
required = list(needs_connection.get("required", []))
|
||||
if not required:
|
||||
pytest.skip("no field is required")
|
||||
connection = full_connection(needs_connection)
|
||||
dropped = required[-1]
|
||||
connection.pop(dropped)
|
||||
if not connection:
|
||||
# The only field is required, and an empty connection counts as none. Send one that has a value
|
||||
# but not the field, which is what a mistyped field name in the credential looks like.
|
||||
connection = {"not_a_field_of_this_server": "x"}
|
||||
|
||||
response = call(client, probe_tool, connection)
|
||||
error = response.json().get("error")
|
||||
assert error, f"a connection without the required field {dropped!r} was served"
|
||||
assert dropped in str(error.get("message", "")), f"the refusal does not name the missing field {dropped!r}: {error}"
|
||||
assert not repeated(response, needs_connection), "the refusal repeats a credential value"
|
||||
|
||||
|
||||
def test_no_reply_repeats_the_credential(client, needs_connection, probe_tool, tools):
|
||||
connection = full_connection(needs_connection)
|
||||
replies = [call(client, probe_tool, connection)]
|
||||
for tool in tools[:5]:
|
||||
replies.append(call(client, tool["name"], connection, arguments={"conformance": "probe"}))
|
||||
replies.append(call(client, "no_such_tool", connection))
|
||||
for response in replies:
|
||||
assert not repeated(response, needs_connection), f"a reply repeats the credential: {response.text[:300]}"
|
||||
|
||||
|
||||
def test_a_malformed_connection_is_no_better_than_none(client, needs_connection, probe_tool):
|
||||
if not EXPECT_FAIL_CLOSED:
|
||||
pytest.skip("CONFORMANCE_EXPECT_FAIL_CLOSED=false")
|
||||
for bad in ("just-a-string", ["a", "list"], 42):
|
||||
params = {"name": probe_tool, "arguments": {}, "_meta": {CONNECTION_KEY: bad}}
|
||||
body = rpc(client, "tools/call", params).json()
|
||||
assert body.get("error"), f"a connection of type {type(bad).__name__} was served"
|
||||
|
||||
|
||||
def test_resources_and_prompts_are_listed_when_advertised(client, initialize):
|
||||
capabilities = initialize.get("capabilities") or {}
|
||||
if capabilities.get("resources"):
|
||||
assert isinstance(result_of(client, "resources/list")["resources"], list)
|
||||
if capabilities.get("prompts"):
|
||||
assert isinstance(result_of(client, "prompts/list")["prompts"], list)
|
||||
117
mcp-servers/gcp-discovery/tests/test_gcp.py
Normal file
117
mcp-servers/gcp-discovery/tests/test_gcp.py
Normal file
@@ -0,0 +1,117 @@
|
||||
import asyncio
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import httpx
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
||||
import mcp_connection # noqa: E402
|
||||
import server # noqa: E402
|
||||
|
||||
CONNECTION = {"scope_root": "organizations/42", "service_account_json": "{}"}
|
||||
|
||||
|
||||
class Google:
|
||||
def __init__(self, results=None, key="results", next_token=None, status=200):
|
||||
self.results, self.key, self.next_token, self.status, self.urls = results or [], key, next_token, status, []
|
||||
|
||||
def __call__(self, request):
|
||||
self.urls.append(request.url)
|
||||
if self.status != 200:
|
||||
return httpx.Response(self.status, json={"error": "ana@customer.example"})
|
||||
body = {self.key: self.results}
|
||||
if self.next_token:
|
||||
body["nextPageToken"] = self.next_token
|
||||
return httpx.Response(200, json=body)
|
||||
|
||||
|
||||
def call(tool, arguments, google, connection=CONNECTION):
|
||||
async def run():
|
||||
client = httpx.AsyncClient(transport=httpx.MockTransport(google))
|
||||
original, token = server.get_upstream_client, server._gcp_token
|
||||
server.get_upstream_client = lambda kind, build: client
|
||||
|
||||
async def fake_token():
|
||||
return "tok"
|
||||
|
||||
server._gcp_token = fake_token
|
||||
bound = mcp_connection.bind(connection)
|
||||
try:
|
||||
return await getattr(server, tool)(arguments)
|
||||
finally:
|
||||
mcp_connection.unbind(bound)
|
||||
server.get_upstream_client, server._gcp_token = original, token
|
||||
await client.aclose()
|
||||
|
||||
return asyncio.run(run())
|
||||
|
||||
|
||||
def test_every_search_is_under_the_scope_root():
|
||||
google = Google([{"name": "//compute.googleapis.com/x"}])
|
||||
assert call("gcp_list_servers", {}, google)["success"]
|
||||
assert google.urls[0].path == "/v1/organizations/42:searchAllResources"
|
||||
assert google.urls[0].params["assetTypes"] == "compute.googleapis.com/Instance"
|
||||
|
||||
|
||||
def test_a_caller_cannot_move_the_scope():
|
||||
google = Google([])
|
||||
call("gcp_list_resources", {"scope": "organizations/99"}, google)
|
||||
assert "organizations/42" in google.urls[0].path
|
||||
|
||||
|
||||
def test_bad_asset_type_is_refused():
|
||||
assert call("gcp_list_resources", {"asset_type": "x y"}, Google())["error"]["code"] == "invalid_argument"
|
||||
|
||||
|
||||
def test_iam_people_are_anonymised_and_service_accounts_kept():
|
||||
policy = {"resource": "//r", "policy": {"bindings": [{"role": "roles/viewer", "members": [
|
||||
"user:ana@customer.example", "group:ops@customer.example", "serviceAccount:scan@p.iam.gserviceaccount.com"]}]}}
|
||||
text = json.dumps(call("gcp_list_resource_policies", {}, Google([policy])))
|
||||
assert "ana@" not in text and "ops@" not in text
|
||||
assert "[user]" in text and "[group]" in text and "scan@p.iam.gserviceaccount.com" in text
|
||||
|
||||
|
||||
def test_organization_policies_use_the_scope_root():
|
||||
google = Google([{"name": "organizations/42/policies/x"}], key="policies")
|
||||
assert call("gcp_list_organization_policies", {}, google)["success"]
|
||||
assert google.urls[0].path == "/v2/organizations/42/policies"
|
||||
|
||||
|
||||
def test_project_outside_scope_is_refused():
|
||||
result = call("gcp_list_recommendations", {"project_id": "other"}, Google([]))
|
||||
assert result["error"]["code"] == "outside_scope"
|
||||
|
||||
|
||||
def test_recommendations_map_to_pillars():
|
||||
google = Google([{"name": "//x/projects/p1", "primaryImpact": {"category": "MANAGEABILITY"}}])
|
||||
|
||||
def handler(request):
|
||||
if "recommender.googleapis.com" in str(request.url):
|
||||
return httpx.Response(200, json={"recommendations": [{"primaryImpact": {"category": "MANAGEABILITY"}}]})
|
||||
return httpx.Response(200, json={"results": [{"name": "//cloudresourcemanager.googleapis.com/projects/p1"}]})
|
||||
|
||||
item = call("gcp_list_recommendations", {"project_id": "p1"}, handler)["data"]["items"][0]
|
||||
assert item["pillar"] == "operations"
|
||||
|
||||
|
||||
def test_upstream_error_text_is_not_returned():
|
||||
text = json.dumps(call("gcp_list_servers", {}, Google(status=403)))
|
||||
assert "403" in text and "ana@" not in text
|
||||
|
||||
|
||||
def test_bad_scope_root_fails_closed():
|
||||
result = call("gcp_list_servers", {}, Google([]), {**CONNECTION, "scope_root": "billingAccounts/1"})
|
||||
assert result["success"] is False
|
||||
|
||||
|
||||
def test_a_throttled_call_waits_and_succeeds():
|
||||
state = {"left": 2}
|
||||
|
||||
def google(request):
|
||||
if state["left"]:
|
||||
state["left"] -= 1
|
||||
return httpx.Response(429, headers={"retry-after": "0"}, json={})
|
||||
return httpx.Response(200, json={"results": [{"name": "//x"}]})
|
||||
|
||||
assert call("gcp_list_servers", {}, google)["data"]["count"] == 1
|
||||
Reference in New Issue
Block a user