Files
Jonathan Boniface bc84ee4df6
Some checks failed
check agents / check (push) Failing after 13s
Solution architecture outcome pattern: agent and its MCP servers
The cp1-solution-architecture-agent and the sa-aws/azure/gcp-cloud MCP servers, a separate
stream from the individual and sub-agent patterns.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 22:13:25 +00:00

2052 lines
100 KiB
Python

"""Solution Architecture AWS
=========================
AWS documentation and read-only estate tools for the Solution Architecture agent, through the customer's read-only role.
Generated by Agent Builder Platform - MCP Server Builder
Version: 0.1.0
Template: mcp-server-template 1.1.0
Features:
- JSON-RPC 2.0 over HTTP (MCP standard)
- Bearer token authentication
- Health check endpoint
- Structured logging (JSON, one object per line)
Environment Variables:
- MCP_REGISTRATION_API_KEY: Authentication key for Gateway registration (required)
- MCP_SERVER_PORT: Server port (default: 8117)
- MCP_SERVER_NAME: Display name for the server
- LOG_LEVEL: Logging level (default: INFO)
- LOG_FORMAT: json (default) or console
"""
import os
import re
import sys
import json
import inspect
import time
import traceback
import asyncio
import logging
import secrets
from typing import Dict, Any, List, Optional, Union # noqa: F401
from collections import OrderedDict
from contextlib import asynccontextmanager
from datetime import datetime, timezone
import structlog
from fastapi import FastAPI, HTTPException, Depends, Request
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from pydantic import BaseModel, Field, StrictInt, StrictStr
import mcp_connection
# Additional imports from tool implementations
import base64
import hashlib
import boto3
from botocore.config import Config as BotoConfig
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
import httpx
TEMPLATE_VERSION = '1.1.0'
# What this server needs to reach its upstream, advertised to the gateway on initialize (None: nothing)
CONNECTION_SCHEMA = {'type': 'object',
'title': 'Solution Architecture AWS',
'description': 'AWS documentation and read-only estate tools for the Solution '
"Architecture agent, through the customer's read-only role.",
'properties': {'access_key_id': {'type': 'string',
'title': 'Access key id',
'description': 'The broker identity that assumes the '
'role.',
'writeOnly': True,
'format': 'password'},
'secret_access_key': {'type': 'string',
'title': 'Secret access key',
'description': 'Its secret key.',
'writeOnly': True,
'format': 'password'},
'role_arn': {'type': 'string',
'title': 'Role ARN',
'description': 'The read-only role.'},
'external_id': {'type': 'string',
'title': 'External id',
'description': "The role's external id.",
'writeOnly': True,
'format': 'password'},
'regions': {'type': 'string',
'title': 'Regions',
'description': 'Comma-separated; the first is the '
'default.'},
'account_ids': {'type': 'string',
'title': 'Account ids',
'description': 'Optional member accounts.'},
'member_role_name': {'type': 'string',
'title': 'Member role name',
'description': "The role's name in member "
'accounts.'},
'docs_access_key_id': {'type': 'string',
'title': 'Documentation access key id',
'description': 'Identity for the AWS '
'documentation server. Defaults '
'to the broker identity.',
'writeOnly': True,
'format': 'password'},
'docs_secret_access_key': {'type': 'string',
'title': 'Documentation secret key',
'description': 'Its secret key.',
'writeOnly': True,
'format': 'password'}},
'required': ['access_key_id', 'secret_access_key', 'role_arn', 'regions'],
'additionalProperties': False}
VERIFY_TOOL = 'verify_connection'
# ============================================
# Configuration
# ============================================
def _load_env_file() -> None:
"""Read the `.env` next to this file, so `cp .env.example .env` and `python server.py` work.
Variables that are already set win, so a container's or a pipeline's settings are never overridden.
The image does not contain a `.env`, so this does nothing there.
"""
path = globals().get("__file__")
if not path:
return
try:
from dotenv import load_dotenv
except ImportError:
return
load_dotenv(os.path.join(os.path.dirname(os.path.abspath(path)), ".env"))
_load_env_file()
class Config:
"""Server configuration from environment variables"""
# Server Identity
SERVER_ID = os.getenv("MCP_SERVER_ID", 'sa-aws-cloud')
SERVER_NAME = os.getenv("MCP_SERVER_NAME", 'Solution Architecture AWS')
SERVER_VERSION = os.getenv("MCP_SERVER_VERSION", '0.1.0')
# MCP_SERVER_PORT, or SERVER_PORT as the ConfigMaps in the tools repo name it
SERVER_PORT = int(os.getenv("MCP_SERVER_PORT") or os.getenv("SERVER_PORT") or "8117")
# Authentication (REQUIRED for MCP Gateway registration)
# Generate secure key: openssl rand -hex 32
MCP_REGISTRATION_API_KEY = os.getenv("MCP_REGISTRATION_API_KEY", "").strip()
# The placeholder from .env.example is not a key: a server started with it unchanged has no key.
if MCP_REGISTRATION_API_KEY.startswith("<"):
MCP_REGISTRATION_API_KEY = ""
# Feature Flags
REQUIRE_AUTH = os.getenv("REQUIRE_AUTH", "true").lower() == "true"
# Applies when CONNECTION_SCHEMA is set: refuse a call that arrives without the tenant's connection
# instead of falling back to this server's own environment. Set to false only for local runs.
REQUIRE_VAULT_CONNECTION = os.getenv("REQUIRE_VAULT_CONNECTION", "true").lower() == "true"
# Logging: LOG_FORMAT is "json" (one object per line, for log stores) or "console" (for reading by eye)
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
LOG_FORMAT = os.getenv("LOG_FORMAT", "json").lower()
config = Config()
# ============================================
# Logging Configuration
# ============================================
def sanitize_log(value: Any, max_length: int = 200) -> str:
"""Make a caller-supplied value safe to log: one line, no control characters, bounded."""
if not isinstance(value, str):
value = str(value)
# Written with .replace() because that is the pattern CodeQL recognises as a
# barrier for py/log-injection (CWE-117).
value = value.replace("\n", "").replace("\r", "")
return re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]", "", value)[:max_length]
def _add_server_identity(_logger, _method, event_dict):
event_dict.setdefault("server_id", config.SERVER_ID)
event_dict.setdefault("server_name", config.SERVER_NAME)
event_dict.setdefault("server_version", config.SERVER_VERSION)
return event_dict
_LEADING_KEYS = (
"timestamp", "level", "event", "logger", "server_id", "server_name", "server_version",
"request_id", "method", "tool",
)
def _scrub_secrets(_logger, _method, event_dict):
"""The last step before a line is written: no credential reaches the log, whoever logged it."""
return mcp_connection.scrub(event_dict)
def _lead_with_common_keys(_logger, _method, event_dict):
"""Every line starts with the same fields in the same order; the event's own follow."""
lead = {key: event_dict.pop(key) for key in _LEADING_KEYS if key in event_dict}
lead.update(event_dict)
return lead
def configure_logging() -> None:
"""Send every log line, ours and the libraries', to stdout in one format."""
level = getattr(logging, config.LOG_LEVEL, logging.INFO)
shared = [
structlog.contextvars.merge_contextvars,
structlog.stdlib.add_logger_name,
structlog.stdlib.add_log_level,
structlog.processors.TimeStamper(fmt="iso", utc=True),
_add_server_identity,
]
renderer = (
structlog.dev.ConsoleRenderer(colors=False)
if config.LOG_FORMAT == "console"
else structlog.processors.JSONRenderer()
)
structlog.configure(
processors=shared + [
structlog.stdlib.PositionalArgumentsFormatter(),
structlog.processors.StackInfoRenderer(),
structlog.processors.format_exc_info,
structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
],
logger_factory=structlog.stdlib.LoggerFactory(),
wrapper_class=structlog.stdlib.BoundLogger,
cache_logger_on_first_use=True,
)
handler = logging.StreamHandler(sys.stdout)
handler.mcp_server_handler = True
handler.setFormatter(structlog.stdlib.ProcessorFormatter(
foreign_pre_chain=shared,
processors=[
structlog.stdlib.ProcessorFormatter.remove_processors_meta,
structlog.processors.format_exc_info,
_lead_with_common_keys,
_scrub_secrets,
renderer,
],
))
root = logging.getLogger()
root.handlers = [h for h in root.handlers if not getattr(h, "mcp_server_handler", False)] + [handler]
root.setLevel(level)
# httpx logs every request URL at INFO, and an upstream URL often carries a key: keep those lines for DEBUG
for name in ("httpx", "httpcore"):
logging.getLogger(name).setLevel(level if level <= logging.DEBUG else logging.WARNING)
# uvicorn installs its own handlers; route them through ours so every line has the same shape
for name in ("uvicorn", "uvicorn.error", "uvicorn.access"):
uvicorn_logger = logging.getLogger(name)
uvicorn_logger.handlers.clear()
uvicorn_logger.propagate = True
configure_logging()
logger = structlog.get_logger(__name__)
# ============================================
# Per-request connection
# ============================================
CONNECTION_METHODS = ("tools/call", "resources/read", "prompts/get")
def get_connection() -> Dict[str, Any]:
"""The connection fields the gateway sent with this request; empty when it sent none."""
return dict(mcp_connection.active() or {})
_client_cache: "OrderedDict[str, Any]" = OrderedDict()
_CLIENT_CACHE_MAX = 32
def get_upstream_client(kind, build):
"""The upstream client of type `kind` for this request's connection.
`build(connection)` runs once per distinct (kind, connection), so two tools that talk to different
upstreams with the same tenant connection each get their own client.
"""
if not isinstance(kind, str) or not kind:
raise TypeError("get_upstream_client needs a client kind, for example get_upstream_client('jira', build)")
key = f"{kind}:{mcp_connection.fingerprint(mcp_connection.active())}"
client = _client_cache.get(key)
if client is None:
client = build(get_connection())
_client_cache[key] = client
while len(_client_cache) > _CLIENT_CACHE_MAX:
_close_client(_client_cache.popitem(last=False)[1])
else:
_client_cache.move_to_end(key)
return client
_closing_tasks: set = set()
def _close_client(client) -> None:
"""Release the connections of a client that left the cache (an httpx client holds a pool of sockets).
Closes with `aclose()`, `close()` or `dispose()` (an httpx client, most clients, a SQLAlchemy engine); a client
with none of them is left to the garbage collector. A failure to close is logged and never reaches the
request that happened to evict it.
"""
close = getattr(client, "aclose", None) or getattr(client, "close", None) or getattr(client, "dispose", None)
if close is None:
return
try:
result = close()
if inspect.isawaitable(result):
try:
task = asyncio.get_running_loop().create_task(result)
except RuntimeError: # no loop to run it on
result.close()
return
_closing_tasks.add(task) # a task nobody refers to can be collected before it finishes
task.add_done_callback(_closing_tasks.discard)
except Exception as error:
logger.warning("client_close_failed", error_type=type(error).__name__, error=sanitize_log(error))
async def _close_all_clients() -> None:
"""On shutdown: close every cached client and wait for the closes already under way."""
while _client_cache:
_close_client(_client_cache.popitem(last=False)[1])
if _closing_tasks:
await asyncio.gather(*list(_closing_tasks), return_exceptions=True)
def check_connection(profile: Optional[Dict[str, Any]]) -> None:
"""Refuse a call with no connection (unless the environment may be used) or with an incomplete one."""
if not profile:
if config.REQUIRE_VAULT_CONNECTION:
raise ValueError(
"No connection was sent with this request: no credential is stored for this tenant. "
"Store one under Credentials, or set REQUIRE_VAULT_CONNECTION=false to use this "
"server's own environment."
)
return
missing = mcp_connection.missing_fields(profile, CONNECTION_SCHEMA)
if missing:
raise ValueError("The connection sent with this request is missing: " + ", ".join(missing))
def render_prompt(template: str, values: Dict[str, Any]) -> str:
"""Fill {{name}} markers in a prompt template; a marker with no value is left as written."""
return re.sub(
r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}",
lambda m: str(values[m.group(1)]) if m.group(1) in values else m.group(0),
template,
)
# ============================================
# Authentication
# ============================================
security = HTTPBearer(auto_error=False)
async def verify_mcp_registration_key(
credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)
) -> bool:
"""
Verify MCP registration API key for /messages endpoint.
This is the industry-standard Bearer token authentication pattern.
"""
# Skip auth if disabled (for testing only!)
if not config.REQUIRE_AUTH:
logger.warning("auth_disabled", detail="testing mode only")
return True
if not credentials:
logger.warning("auth_missing_credentials")
raise HTTPException(
status_code=401,
detail="Missing authentication credentials. Include 'Authorization: Bearer <token>' header.",
headers={"WWW-Authenticate": "Bearer"}
)
provided_key = credentials.credentials
expected_key = config.MCP_REGISTRATION_API_KEY
if not expected_key:
logger.error("auth_key_not_configured")
raise HTTPException(
status_code=500,
detail="Server authentication not configured"
)
if not secrets.compare_digest(provided_key.encode("utf-8"), expected_key.encode("utf-8")):
logger.warning("auth_invalid_key")
raise HTTPException(
status_code=401,
detail="Invalid authentication credentials",
headers={"WWW-Authenticate": "Bearer"}
)
return True
# ============================================
# MCP Protocol Models
# ============================================
class MCPRequest(BaseModel):
"""JSON-RPC 2.0 request (MCP standard)"""
jsonrpc: str = "2.0"
id: Union[StrictStr, StrictInt] # JSON-RPC allows a string or a number; the reply echoes it unchanged
method: str
params: Dict[str, Any] = Field(default_factory=dict)
class MCPResponse(BaseModel):
"""JSON-RPC 2.0 response (MCP standard)"""
jsonrpc: str = "2.0"
id: Union[StrictStr, StrictInt]
result: Optional[Dict[str, Any]] = None
error: Optional[Dict[str, Any]] = None
# ============================================
# Tool Definitions
# ============================================
TOOLS_REGISTRY = [
{
"name": 'aws_check_connection',
"description": 'Test the stored connection: assume the role and read its identity. Returns no customer data.',
"inputSchema": {'type': 'object', 'properties': {}, 'required': []}
},
{
"name": 'aws_search_documents',
"description": 'Search AWS documentation in free text. Queries are sent as written and logged.',
"inputSchema": {'type': 'object',
'properties': {'query': {'type': 'string',
'description': 'What to look up. Keep client detail out.'}},
'required': ['query']}
},
{
"name": 'aws_get_documents',
"description": 'Read one AWS documentation page by URL.',
"inputSchema": {'type': 'object',
'properties': {'url': {'type': 'string', 'description': 'A docs.aws.amazon.com URL.'}},
'required': ['url']}
},
{
"name": 'aws_search_projects',
"description": "List the organisation's accounts.",
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_assets',
"description": 'List tagged resources.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_instances',
"description": 'List EC2 instances.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_instance_group_managers',
"description": 'List Auto Scaling groups.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_instance_templates',
"description": 'List launch templates.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_disks',
"description": 'List EBS volumes.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_reservations',
"description": 'List capacity reservations.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_commitments',
"description": 'List Savings Plans.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_clusters',
"description": 'List EKS clusters.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_services',
"description": 'List App Runner services.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_functions',
"description": 'List Lambda functions.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_sql_instances',
"description": 'List RDS instances.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_buckets',
"description": 'List S3 buckets.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_topics',
"description": 'List SNS topics.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_subscriptions',
"description": 'List SNS subscriptions.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_roles',
"description": 'List IAM roles.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_deny_policies',
"description": 'List service control policies.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_alert_policies',
"description": 'List CloudWatch metric alarms.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_dashboards',
"description": 'List CloudWatch dashboards.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_metric_descriptors',
"description": 'List CloudWatch metrics.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_connectivity_tests',
"description": 'List Reachability Analyzer paths.',
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': []}
},
{
"name": 'aws_list_node_pools',
"description": "List one EKS cluster's node groups.",
"inputSchema": {'type': 'object',
'properties': {'cluster': {'type': 'string', 'description': "The cluster's name."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': ['cluster']}
},
{
"name": 'aws_list_instance_attached_disks',
"description": 'List the EBS volumes attached to one instance.',
"inputSchema": {'type': 'object',
'properties': {'instance_id': {'type': 'string', 'description': 'The instance id.'},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'},
'page_size': {'type': 'integer',
'description': 'Items per page, up to 200. Default 50.'},
'page_token': {'type': 'string',
'description': 'next_page_token from the previous '
'reply.'}},
'required': ['instance_id']}
},
{
"name": 'aws_get_instance_basic_info',
"description": 'Read one EC2 instance.',
"inputSchema": {'type': 'object',
'properties': {'instance_id': {'type': 'string', 'description': 'The instance id.'},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['instance_id']}
},
{
"name": 'aws_get_instance_group_manager_basic_info',
"description": 'Read one Auto Scaling group.',
"inputSchema": {'type': 'object',
'properties': {'name': {'type': 'string', 'description': "The group's name."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['name']}
},
{
"name": 'aws_get_instance_template_properties',
"description": "Read a launch template's versions.",
"inputSchema": {'type': 'object',
'properties': {'template_id': {'type': 'string', 'description': 'The template id.'},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['template_id']}
},
{
"name": 'aws_get_disk_basic_info',
"description": 'Read one EBS volume.',
"inputSchema": {'type': 'object',
'properties': {'volume_id': {'type': 'string', 'description': 'The volume id.'},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['volume_id']}
},
{
"name": 'aws_get_cluster',
"description": 'Read one EKS cluster.',
"inputSchema": {'type': 'object',
'properties': {'name': {'type': 'string', 'description': "The cluster's name."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['name']}
},
{
"name": 'aws_get_node_pool',
"description": 'Read one EKS node group.',
"inputSchema": {'type': 'object',
'properties': {'cluster': {'type': 'string', 'description': "The cluster's name."},
'name': {'type': 'string', 'description': "The node group's name."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['cluster', 'name']}
},
{
"name": 'aws_get_k8s_version',
"description": "Read EKS's supported Kubernetes versions.",
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': []}
},
{
"name": 'aws_get_service',
"description": 'Read one App Runner service.',
"inputSchema": {'type': 'object',
'properties': {'arn': {'type': 'string', 'description': "The service's ARN."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['arn']}
},
{
"name": 'aws_get_function',
"description": "Read one Lambda function's configuration.",
"inputSchema": {'type': 'object',
'properties': {'name': {'type': 'string', 'description': "The function's name."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['name']}
},
{
"name": 'aws_get_sql_instance',
"description": 'Read one RDS instance.',
"inputSchema": {'type': 'object',
'properties': {'name': {'type': 'string', 'description': "The instance's identifier."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['name']}
},
{
"name": 'aws_get_topic',
"description": 'Read one SNS topic.',
"inputSchema": {'type': 'object',
'properties': {'arn': {'type': 'string', 'description': "The topic's ARN."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['arn']}
},
{
"name": 'aws_get_subscription',
"description": 'Read one SNS subscription.',
"inputSchema": {'type': 'object',
'properties': {'arn': {'type': 'string', 'description': "The subscription's ARN."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['arn']}
},
{
"name": 'aws_get_role',
"description": 'Read one IAM role.',
"inputSchema": {'type': 'object',
'properties': {'name': {'type': 'string', 'description': "The role's name."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['name']}
},
{
"name": 'aws_get_deny_policy',
"description": 'Read one service control policy.',
"inputSchema": {'type': 'object',
'properties': {'policy_id': {'type': 'string', 'description': 'The policy id.'},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['policy_id']}
},
{
"name": 'aws_get_alert_policy',
"description": 'Read named CloudWatch alarms.',
"inputSchema": {'type': 'object',
'properties': {'name': {'type': 'string', 'description': "The alarm's name."},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['name']}
},
{
"name": 'aws_get_connectivity_test',
"description": 'Read one Reachability Analyzer path.',
"inputSchema": {'type': 'object',
'properties': {'path_id': {'type': 'string', 'description': 'The path id.'},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['path_id']}
},
{
"name": 'aws_analyze_access',
"description": "Read the account's IAM users, groups, roles and policies.",
"inputSchema": {'type': 'object',
'properties': {'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': []}
},
{
"name": 'aws_list_timeseries',
"description": 'Read CloudWatch metric values.',
"inputSchema": {'type': 'object',
'properties': {'metric_queries': {'type': 'array',
'description': 'CloudWatch MetricDataQueries.'},
'start_time': {'type': 'string', 'description': 'ISO 8601 start.'},
'end_time': {'type': 'string', 'description': 'ISO 8601 end.'},
'account_id': {'type': 'string',
'description': 'A member account of the connection.'},
'region': {'type': 'string',
'description': "One of the connection's regions; the first "
'by default.'}},
'required': ['metric_queries', 'start_time', 'end_time']}
},
{
"name": 'verify_connection',
"description": (
"Check that the connection sent with this request works against the upstream, and say who it "
"authenticated as. Makes no change."
),
"inputSchema": {'type': 'object', 'properties': {}, 'required': []}
}
]
# ============================================
# Resource Definitions
# ============================================
RESOURCES_REGISTRY = []
# ============================================
# Prompt Definitions
# ============================================
PROMPT_TEMPLATES = {}
PROMPTS_REGISTRY = [
{
"name": name,
"description": prompt["description"],
"arguments": [
{"name": a["name"], "description": a["description"], "required": a["required"]}
for a in prompt["arguments"]
],
}
for name, prompt in PROMPT_TEMPLATES.items()
]
# ============================================
# Tool Implementations
# ============================================
DEFAULT_PAGE_SIZE = 50
MAX_PAGE_SIZE = 200
MAX_RESPONSE_BYTES = 200000
RETRY_ATTEMPTS = 5
RETRY_MAX_WAIT_SECONDS = 20
RETRY_BUDGET_SECONDS = 60
SECRET_KEYS = (
"userdata", "customdata", "customscript", "protectedsettings", "connectionstring", "connectionstrings",
"appsettings", "env", "envvars", "environmentvariables", "variables", "password", "adminpassword", "secret",
"secretvalue", "sastoken", "accesskey", "primarykey", "secondarykey", "privatekey", "kubeconfig", "credentials",
)
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)}}
AWS_SESSIONS = {}
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
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
def _docs_query_logged(provider: str, tool: str, query: Any) -> None:
logger.info("docs_query", provider=provider, tool=tool, query=str(query))
DOCS_MAX_TEXT = 20000
async def _docs_call(provider: str, connection: Dict[str, Any], name: str, arguments: Dict[str, Any]) -> List[Dict[str, Any]]:
"""Call one tool on the vendor's documentation server, once that server says it still offers it."""
session = await _knowledge_session(provider, connection)
tools = {t.get("name") 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": arguments}}, session)
parts = _knowledge_message(response).get("result", {}).get("content", [])
return [{"text": str(p.get("text"))[:DOCS_MAX_TEXT]} for p in parts if p.get("type") == "text"]
async def _docs_search(provider: str, tool: str, arguments: Dict[str, Any], connection: Dict[str, Any]) -> Dict[str, Any]:
query = str(arguments.get("query") or "").strip()
if not query:
return _refuse("invalid_argument", "query is required")
_docs_query_logged(provider, tool, query)
try:
found = await _knowledge_search(provider, connection, query)
except Exception as error:
return _upstream_failed(provider, error)
return _page_result(provider, tool, arguments, found, None, None)
async def _docs_read(provider: str, tool: str, arguments: Dict[str, Any], connection: Dict[str, Any], name: str,
field: str, shape=None) -> Dict[str, Any]:
target = arguments.get(field)
if not target:
return _refuse("invalid_argument", f"{field} is required")
_docs_query_logged(provider, tool, target)
try:
found = await _docs_call(provider, connection, name, shape(target) if shape else {field: target})
except Exception as error:
return _upstream_failed(provider, error)
return _page_result(provider, tool, arguments, found, None, None)
async def _aws_list(tool: str, arguments: Dict[str, Any], entry: tuple, wanted: Optional[List[str]] = None) -> Dict[str, Any]:
"""One page; `wanted` adds caller values to the fixed request, as (parameter, argument) pairs of a required value."""
service, operation, result_key, token_in, token_out, fixed = entry
fixed = dict(fixed)
for parameter, argument in wanted or []:
if not arguments.get(argument):
return _refuse("invalid_argument", f"{argument} is required")
fixed[parameter] = arguments[argument]
return await _aws_kind(tool, {**arguments, "kind": "one"}, {"one": (service, operation, result_key, token_in, token_out, fixed)}, "one")
async def _aws_get(tool: str, arguments: Dict[str, Any], service: str, operation: str, request: Dict[str, Any]) -> Dict[str, Any]:
account, region, refused = _aws_target(arguments)
if refused:
return refused
missing = [k for k, v in request.items() if v in (None, "", [], [None])]
if missing:
return _refuse("invalid_argument", "missing: " + ", ".join(missing))
try:
body = await _aws_call(arguments, service, operation, region, **request)
except Exception as error:
return _upstream_failed("aws", error)
body.pop("ResponseMetadata", None)
return _one_result("aws", tool, arguments, body)
async def _aws_metric_data(tool: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
queries, start, end = arguments.get("metric_queries"), arguments.get("start_time"), arguments.get("end_time")
if not isinstance(queries, list) or not queries or not start or not end:
return _refuse("invalid_argument", "metric_queries, start_time and end_time are required")
return await _aws_get(tool, arguments, "cloudwatch", "get_metric_data",
{"MetricDataQueries": queries, "StartTime": start, "EndTime": end})
def _aws_docs_connection() -> Dict[str, Any]:
connection = get_connection()
return {"aws_access_key_id": connection.get("docs_access_key_id") or connection.get("access_key_id"),
"aws_secret_access_key": connection.get("docs_secret_access_key") or connection.get("secret_access_key")}
def _aws_docs_request(url: Any) -> Dict[str, Any]:
"""The call shape AWS's documentation reader takes (agent-toolkit-for-aws)."""
return {"requests": [{"url": url, "max_length": 100000}]}
async def aws_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
try:
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, "message": "Assumed the role."}
async def aws_search_documents(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _docs_search("aws", "aws_search_documents", arguments, _aws_docs_connection())
async def aws_get_documents(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _docs_read("aws", "aws_get_documents", arguments, _aws_docs_connection(), "aws___read_documentation", "url", _aws_docs_request)
async def aws_search_projects(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_search_projects", arguments, ('organizations', 'list_accounts', 'Accounts', 'NextToken', 'NextToken', {}))
async def aws_list_assets(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_assets", arguments, ('resourcegroupstaggingapi', 'get_resources', 'ResourceTagMappingList', 'PaginationToken', 'PaginationToken', {}))
async def aws_list_instances(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_instances", arguments, ('ec2', 'describe_instances', 'Reservations', 'NextToken', 'NextToken', {}))
async def aws_list_instance_group_managers(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_instance_group_managers", arguments, ('autoscaling', 'describe_auto_scaling_groups', 'AutoScalingGroups', 'NextToken', 'NextToken', {}))
async def aws_list_instance_templates(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_instance_templates", arguments, ('ec2', 'describe_launch_templates', 'LaunchTemplates', 'NextToken', 'NextToken', {}))
async def aws_list_disks(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_disks", arguments, ('ec2', 'describe_volumes', 'Volumes', 'NextToken', 'NextToken', {}))
async def aws_list_reservations(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_reservations", arguments, ('ec2', 'describe_capacity_reservations', 'CapacityReservations', 'NextToken', 'NextToken', {}))
async def aws_list_commitments(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_commitments", arguments, ('savingsplans', 'describe_savings_plans', 'savingsPlans', 'nextToken', 'nextToken', {}))
async def aws_list_clusters(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_clusters", arguments, ('eks', 'list_clusters', 'clusters', 'nextToken', 'nextToken', {}))
async def aws_list_services(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_services", arguments, ('apprunner', 'list_services', 'ServiceSummaryList', 'NextToken', 'NextToken', {}))
async def aws_list_functions(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_functions", arguments, ('lambda', 'list_functions', 'Functions', 'Marker', 'NextMarker', {}))
async def aws_list_sql_instances(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_sql_instances", arguments, ('rds', 'describe_db_instances', 'DBInstances', 'Marker', 'Marker', {}))
async def aws_list_buckets(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_buckets", arguments, ('s3', 'list_buckets', 'Buckets', 'ContinuationToken', 'ContinuationToken', {}))
async def aws_list_topics(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_topics", arguments, ('sns', 'list_topics', 'Topics', 'NextToken', 'NextToken', {}))
async def aws_list_subscriptions(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_subscriptions", arguments, ('sns', 'list_subscriptions', 'Subscriptions', 'NextToken', 'NextToken', {}))
async def aws_list_roles(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_roles", arguments, ('iam', 'list_roles', 'Roles', 'Marker', 'Marker', {}))
async def aws_list_deny_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_deny_policies", arguments, ('organizations', 'list_policies', 'Policies', 'NextToken', 'NextToken', {'Filter': 'SERVICE_CONTROL_POLICY'}))
async def aws_list_alert_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_alert_policies", arguments, ('cloudwatch', 'describe_alarms', 'MetricAlarms', 'NextToken', 'NextToken', {}))
async def aws_list_dashboards(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_dashboards", arguments, ('cloudwatch', 'list_dashboards', 'DashboardEntries', 'NextToken', 'NextToken', {}))
async def aws_list_metric_descriptors(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_metric_descriptors", arguments, ('cloudwatch', 'list_metrics', 'Metrics', 'NextToken', 'NextToken', {}))
async def aws_list_connectivity_tests(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_connectivity_tests", arguments, ('ec2', 'describe_network_insights_paths', 'NetworkInsightsPaths', 'NextToken', 'NextToken', {}))
async def aws_list_node_pools(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_list("aws_list_node_pools", arguments, ("eks", "list_nodegroups", "nodegroups", "nextToken", "nextToken", {}), [("clusterName", "cluster")])
async def aws_list_instance_attached_disks(arguments: Dict[str, Any]) -> Dict[str, Any]:
instance = arguments.get("instance_id")
if not instance:
return _refuse("invalid_argument", "instance_id is required")
return await _aws_list("aws_list_instance_attached_disks", arguments, ("ec2", "describe_volumes", "Volumes", "NextToken", "NextToken", {"Filters": [{"Name": "attachment.instance-id", "Values": [str(instance)]}]}))
async def aws_get_instance_basic_info(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_instance_basic_info", arguments, "ec2", "describe_instances", {"InstanceIds": [arguments.get("instance_id")]})
async def aws_get_instance_group_manager_basic_info(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_instance_group_manager_basic_info", arguments, "autoscaling", "describe_auto_scaling_groups", {"AutoScalingGroupNames": [arguments.get("name")]})
async def aws_get_instance_template_properties(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_instance_template_properties", arguments, "ec2", "describe_launch_template_versions", {"LaunchTemplateId": arguments.get("template_id")})
async def aws_get_disk_basic_info(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_disk_basic_info", arguments, "ec2", "describe_volumes", {"VolumeIds": [arguments.get("volume_id")]})
async def aws_get_cluster(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_cluster", arguments, "eks", "describe_cluster", {"name": arguments.get("name")})
async def aws_get_node_pool(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_node_pool", arguments, "eks", "describe_nodegroup", {"clusterName": arguments.get("cluster"), "nodegroupName": arguments.get("name")})
async def aws_get_k8s_version(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_k8s_version", arguments, "eks", "describe_cluster_versions", {})
async def aws_get_service(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_service", arguments, "apprunner", "describe_service", {"ServiceArn": arguments.get("arn")})
async def aws_get_function(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_function", arguments, "lambda", "get_function_configuration", {"FunctionName": arguments.get("name")})
async def aws_get_sql_instance(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_sql_instance", arguments, "rds", "describe_db_instances", {"DBInstanceIdentifier": arguments.get("name")})
async def aws_get_topic(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_topic", arguments, "sns", "get_topic_attributes", {"TopicArn": arguments.get("arn")})
async def aws_get_subscription(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_subscription", arguments, "sns", "get_subscription_attributes", {"SubscriptionArn": arguments.get("arn")})
async def aws_get_role(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_role", arguments, "iam", "get_role", {"RoleName": arguments.get("name")})
async def aws_get_deny_policy(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_deny_policy", arguments, "organizations", "describe_policy", {"PolicyId": arguments.get("policy_id")})
async def aws_get_alert_policy(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_alert_policy", arguments, "cloudwatch", "describe_alarms", {"AlarmNames": [arguments.get("name")]})
async def aws_get_connectivity_test(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_get_connectivity_test", arguments, "ec2", "describe_network_insights_paths", {"NetworkInsightsPathIds": [arguments.get("path_id")]})
async def aws_analyze_access(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_get("aws_analyze_access", arguments, "iam", "get_account_authorization_details", {})
async def aws_list_timeseries(arguments: Dict[str, Any]) -> Dict[str, Any]:
return await _aws_metric_data("aws_list_timeseries", arguments)
async def verify_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
"""Check that the connection sent with this request works against the upstream. Makes no change."""
connection = get_connection()
if not connection:
return {"ok": False, "message": "No connection was sent with this request."}
missing = mcp_connection.missing_fields(connection, CONNECTION_SCHEMA)
if missing:
return {"ok": False, "message": "The connection is missing: " + ", ".join(missing)}
return await aws_check_connection(arguments)
# Tool function registry
TOOL_FUNCTIONS = {
'aws_check_connection': aws_check_connection,
'aws_search_documents': aws_search_documents,
'aws_get_documents': aws_get_documents,
'aws_search_projects': aws_search_projects,
'aws_list_assets': aws_list_assets,
'aws_list_instances': aws_list_instances,
'aws_list_instance_group_managers': aws_list_instance_group_managers,
'aws_list_instance_templates': aws_list_instance_templates,
'aws_list_disks': aws_list_disks,
'aws_list_reservations': aws_list_reservations,
'aws_list_commitments': aws_list_commitments,
'aws_list_clusters': aws_list_clusters,
'aws_list_services': aws_list_services,
'aws_list_functions': aws_list_functions,
'aws_list_sql_instances': aws_list_sql_instances,
'aws_list_buckets': aws_list_buckets,
'aws_list_topics': aws_list_topics,
'aws_list_subscriptions': aws_list_subscriptions,
'aws_list_roles': aws_list_roles,
'aws_list_deny_policies': aws_list_deny_policies,
'aws_list_alert_policies': aws_list_alert_policies,
'aws_list_dashboards': aws_list_dashboards,
'aws_list_metric_descriptors': aws_list_metric_descriptors,
'aws_list_connectivity_tests': aws_list_connectivity_tests,
'aws_list_node_pools': aws_list_node_pools,
'aws_list_instance_attached_disks': aws_list_instance_attached_disks,
'aws_get_instance_basic_info': aws_get_instance_basic_info,
'aws_get_instance_group_manager_basic_info': aws_get_instance_group_manager_basic_info,
'aws_get_instance_template_properties': aws_get_instance_template_properties,
'aws_get_disk_basic_info': aws_get_disk_basic_info,
'aws_get_cluster': aws_get_cluster,
'aws_get_node_pool': aws_get_node_pool,
'aws_get_k8s_version': aws_get_k8s_version,
'aws_get_service': aws_get_service,
'aws_get_function': aws_get_function,
'aws_get_sql_instance': aws_get_sql_instance,
'aws_get_topic': aws_get_topic,
'aws_get_subscription': aws_get_subscription,
'aws_get_role': aws_get_role,
'aws_get_deny_policy': aws_get_deny_policy,
'aws_get_alert_policy': aws_get_alert_policy,
'aws_get_connectivity_test': aws_get_connectivity_test,
'aws_analyze_access': aws_analyze_access,
'aws_list_timeseries': aws_list_timeseries,
'verify_connection': verify_connection,
}
# ============================================
# Resource Implementations
# ============================================
# Resource read handlers by uri
RESOURCE_HANDLERS = {
}
# ============================================
# FastAPI Application
# ============================================
@asynccontextmanager
async def lifespan(app: FastAPI):
"""Application lifespan manager"""
logger.info(
"server_starting",
port=config.SERVER_PORT,
auth_required=config.REQUIRE_AUTH,
tools=len(TOOLS_REGISTRY),
resources=len(RESOURCES_REGISTRY),
prompts=len(PROMPTS_REGISTRY),
template_version=TEMPLATE_VERSION,
)
# Validate configuration
if config.REQUIRE_AUTH and not config.MCP_REGISTRATION_API_KEY:
logger.error(
"registration_key_not_set",
hint="Set MCP_REGISTRATION_API_KEY before starting the server",
)
yield
await _close_all_clients()
logger.info("server_stopping")
app = FastAPI(
title=config.SERVER_NAME,
version=config.SERVER_VERSION,
description="AWS documentation and read-only estate tools for the Solution Architecture agent, through the customer's read-only role.",
lifespan=lifespan
)
# FastAPI's default answer to an invalid request repeats it, and the request can carry the tenant's connection
mcp_connection.install_invalid_request_handler(
app, lambda fields: logger.warning("invalid_request", fields=sanitize_log(fields))
)
# ============================================
# Health Check Endpoint
# ============================================
@app.get("/health")
async def health_check():
"""
Health check endpoint (no authentication required).
Used by:
- MCP Gateway health monitoring
- Kubernetes liveness/readiness probes
- Load balancers
"""
# Answers without a key, so it says only what a probe needs: not how authentication is set up
return {
"status": "healthy" if config.MCP_REGISTRATION_API_KEY else "degraded",
"server_id": config.SERVER_ID,
"server_name": config.SERVER_NAME,
"version": config.SERVER_VERSION,
"timestamp": datetime.now(timezone.utc).isoformat(),
}
# ============================================
# MCP Authentication Info Endpoint
# ============================================
@app.get("/.well-known/mcp-auth")
async def mcp_auth_info():
"""
MCP Authentication Information Endpoint (PUBLIC - no auth required).
Exposes authentication requirements for Gateway registration.
"""
return {
"auth_required": config.REQUIRE_AUTH,
"auth_type": "bearer",
"description": "Include 'Authorization: Bearer <MCP_REGISTRATION_API_KEY>' header",
"env_var": "MCP_REGISTRATION_API_KEY"
}
# ============================================
# MCP Protocol /messages Endpoint
# ============================================
class _MethodNotFound(Exception):
"""The JSON-RPC method is not one this server answers."""
async def dispatch_mcp_request(request: MCPRequest) -> MCPResponse:
"""Run one JSON-RPC request; every outcome, errors included, is an MCPResponse."""
# The tenant's connection, bound for this request only so tools reach the right account
connection_token = mcp_connection.bind(mcp_connection.from_params(request.params))
try:
if CONNECTION_SCHEMA is not None and request.method in CONNECTION_METHODS:
check_connection(mcp_connection.active())
if request.method == "initialize":
result = {
"protocolVersion": "1.0.0",
"serverInfo": {
"name": config.SERVER_NAME,
"version": config.SERVER_VERSION,
"server_id": config.SERVER_ID
},
"capabilities": {
"tools": True,
"resources": False,
"prompts": False
},
"authentication": {
"type": "bearer",
"description": "Requires MCP_REGISTRATION_API_KEY in Authorization header"
}
}
if CONNECTION_SCHEMA is not None:
result["_meta"] = mcp_connection.schema_meta(CONNECTION_SCHEMA, verify_tool=VERIFY_TOOL)
return MCPResponse(id=request.id, result=result)
elif request.method == "tools/list":
return MCPResponse(id=request.id, result={"tools": TOOLS_REGISTRY})
elif request.method == "tools/call":
tool_name = request.params.get("name")
arguments = request.params.get("arguments")
if arguments is None:
arguments = {}
if not tool_name:
raise ValueError("Missing 'name' in params")
if not isinstance(tool_name, str):
raise ValueError("'name' must be a string")
if not isinstance(arguments, dict):
raise ValueError("'arguments' must be an object")
structlog.contextvars.bind_contextvars(tool=sanitize_log(tool_name))
tool_func = TOOL_FUNCTIONS.get(tool_name)
if not tool_func:
raise ValueError(f"Unknown tool: {tool_name}")
result = await tool_func(arguments)
if isinstance(result, dict) and result.get("success") is False and isinstance(result.get("error"), str):
# A failed call's message often quotes the upstream URL, which may carry a key
result = {**result, "error": mcp_connection.scrub(result["error"])}
reply = {
"content": [
{
"type": "text",
"text": json.dumps(result) if isinstance(result, dict) else str(result)
}
]
}
if isinstance(result, dict) and result.get("success") is False:
# A tool that reports failure is an error to the caller too (MCP: isError), not a normal result
reply["isError"] = True
return MCPResponse(id=request.id, result=reply)
elif request.method == "resources/list":
return MCPResponse(id=request.id, result={"resources": RESOURCES_REGISTRY})
elif request.method == "resources/read":
uri = request.params.get("uri")
if not uri:
raise ValueError("Missing 'uri' in params")
structlog.contextvars.bind_contextvars(resource=sanitize_log(uri))
handler = RESOURCE_HANDLERS.get(uri)
if not handler:
raise ValueError(f"Unknown resource: {uri}")
content = await handler(uri)
mime_type = next((r["mimeType"] for r in RESOURCES_REGISTRY if r["uri"] == uri), "text/plain")
text = content if isinstance(content, str) else json.dumps(content)
return MCPResponse(id=request.id, result={
"contents": [{"uri": uri, "mimeType": mime_type, "text": text}]
})
elif request.method == "prompts/list":
return MCPResponse(id=request.id, result={"prompts": PROMPTS_REGISTRY})
elif request.method == "prompts/get":
prompt_name = request.params.get("name")
prompt = PROMPT_TEMPLATES.get(prompt_name) if isinstance(prompt_name, str) else None
if prompt is None:
raise ValueError(f"Unknown prompt: {prompt_name}")
structlog.contextvars.bind_contextvars(prompt=sanitize_log(prompt_name))
supplied = request.params.get("arguments") or {}
values = {a["name"]: a["default"] for a in prompt["arguments"] if a["default"] is not None}
values.update(supplied)
missing = [a["name"] for a in prompt["arguments"] if a["required"] and a["name"] not in values]
if missing:
raise ValueError("Missing prompt argument(s): " + ", ".join(missing))
return MCPResponse(id=request.id, result={
"description": prompt["description"],
"messages": [{
"role": "user",
"content": {"type": "text", "text": render_prompt(prompt["template"], values)},
}],
})
else:
raise _MethodNotFound(f"Unknown method: {request.method}")
except _MethodNotFound as e:
logger.warning("mcp_method_not_found", error=sanitize_log(mcp_connection.redact(e)))
return MCPResponse(id=request.id, error={"code": -32601, "message": mcp_connection.redact(e)})
except NotImplementedError as e:
message = mcp_connection.redact(e)
logger.warning("tool_not_implemented", error=sanitize_log(message))
return MCPResponse(id=request.id, error={"code": -32601, "message": message})
except ValueError as e:
message = mcp_connection.redact(e)
logger.warning("mcp_client_error", error=sanitize_log(message))
return MCPResponse(id=request.id, error={"code": -32602, "message": message})
except Exception as e:
# The message of an unexpected error is not shown to the caller and is redacted before it is logged;
# a tool may have put the connection's credential in it.
logger.error(
"mcp_unexpected_error",
error_type=type(e).__name__,
error=sanitize_log(mcp_connection.redact(e)),
traceback=sanitize_log(mcp_connection.redact(traceback.format_exc())),
)
return MCPResponse(id=request.id, error={"code": -32603, "message": "Internal server error"})
finally:
mcp_connection.unbind(connection_token)
@app.post("/messages")
async def handle_mcp_message(
request: MCPRequest,
http_request: Request,
authenticated: bool = Depends(verify_mcp_registration_key)
) -> MCPResponse:
"""
MCP protocol message handler (JSON-RPC 2.0 over HTTP).
This is the STANDARD MCP endpoint for Gateway integration.
Requires Bearer token authentication (MCP_REGISTRATION_API_KEY).
Supported Methods:
- initialize: Protocol handshake and capability exchange
- tools/list: Discover available tools
- tools/call: Execute a specific tool
- resources/list: List available resources
- prompts/list: List available prompts
"""
started = time.monotonic()
structlog.contextvars.clear_contextvars()
structlog.contextvars.bind_contextvars(
request_id=sanitize_log(http_request.headers.get("x-request-id") or str(request.id)),
method=sanitize_log(request.method),
)
try:
response = await dispatch_mcp_request(request)
completed = {}
if CONNECTION_SCHEMA is not None and request.method in CONNECTION_METHODS:
# Which connection served the call: a short id, never the credential
completed["connection"] = mcp_connection.fingerprint(mcp_connection.from_params(request.params))
logger.info(
"mcp_request_completed",
outcome="error" if response.error else ("tool_error" if (response.result or {}).get("isError") else "ok"),
error_code=(response.error or {}).get("code"),
duration_ms=round((time.monotonic() - started) * 1000, 1),
**completed,
)
return response
finally:
structlog.contextvars.clear_contextvars()
# ============================================
# Entry Point
# ============================================
if __name__ == "__main__":
import uvicorn
uvicorn.run(
"server:app",
host="0.0.0.0",
port=config.SERVER_PORT,
log_level=logging.getLevelName(getattr(logging, config.LOG_LEVEL, logging.INFO)).lower(),
log_config=None, # configure_logging() owns the format
access_log=True,
reload=False # Set to True for development
)