Solution architecture outcome pattern: agent and its MCP servers
Some checks failed
check agents / check (push) Failing after 13s
Some checks failed
check agents / check (push) Failing after 13s
The cp1-solution-architecture-agent and the sa-aws/azure/gcp-cloud MCP servers, a separate stream from the individual and sub-agent patterns. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,62 @@
|
||||
# ============================================
|
||||
# Solution Architecture Azure - 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://solution-architecture-azure:8116
|
||||
# ============================================
|
||||
|
||||
# Server Identity
|
||||
MCP_SERVER_NAME=Solution Architecture Azure
|
||||
MCP_SERVER_ID=sa-azure-cloud
|
||||
MCP_SERVER_VERSION=0.1.0
|
||||
|
||||
# Server Configuration
|
||||
MCP_SERVER_PORT=8116
|
||||
|
||||
# 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
outcome-pattern/solution_architecture/mcp-servers/sa-azure-cloud/.gitignore
vendored
Normal file
15
outcome-pattern/solution_architecture/mcp-servers/sa-azure-cloud/.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/
|
||||
@@ -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="Azure documentation and read-only estate tools for the Solution Architecture agent, through Microsoft Learn, Resource Graph and ARM."
|
||||
LABEL version="0.1.0"
|
||||
LABEL server.id="sa-azure-cloud"
|
||||
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=8116
|
||||
ENV LOG_LEVEL=INFO
|
||||
ENV LOG_FORMAT=json
|
||||
|
||||
# Expose port
|
||||
EXPOSE 8116
|
||||
|
||||
# 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 '8116'))" || exit 1
|
||||
|
||||
# Run the server
|
||||
CMD ["python", "server.py"]
|
||||
@@ -0,0 +1,228 @@
|
||||
# Solution Architecture Azure
|
||||
|
||||
Azure documentation and read-only estate tools for the Solution Architecture agent, through Microsoft Learn, Resource Graph and ARM.
|
||||
|
||||
**Version:** 0.1.0
|
||||
**Server ID:** sa-azure-cloud
|
||||
**Port:** 8116
|
||||
|
||||
---
|
||||
|
||||
## 🚀 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>:8116`.
|
||||
|
||||
### 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_search_documents**: Search Microsoft Learn in free text. Queries are sent as written and logged.
|
||||
- **azure_get_documents**: Fetch one Microsoft Learn page by URL.
|
||||
- **azure_analyze_access**: List role assignments, optionally for one principal or below one scope.
|
||||
- **azure_list_instance_attached_disks**: List the disks attached to one virtual machine.
|
||||
- **azure_list_node_pools**: List AKS node pools.
|
||||
- **azure_search_subscriptions**: List subscriptions.
|
||||
- **azure_list_instances**: List virtual machines.
|
||||
- **azure_list_instance_group_managers**: List scale sets.
|
||||
- **azure_list_instance_templates**: List template specs and gallery images.
|
||||
- **azure_list_disks**: List managed disks.
|
||||
- **azure_list_reservations**: List capacity reservation groups.
|
||||
- **azure_list_clusters**: List AKS clusters.
|
||||
- **azure_list_services**: List Container Apps and App Service apps.
|
||||
- **azure_list_sql_instances**: List SQL, PostgreSQL and MySQL servers.
|
||||
- **azure_list_buckets**: List storage accounts.
|
||||
- **azure_list_topics**: List Service Bus, Event Hubs and Event Grid topics.
|
||||
- **azure_list_roles**: List role definitions.
|
||||
- **azure_list_alert_policies**: List alert rules.
|
||||
- **azure_list_dashboards**: List dashboards.
|
||||
- **azure_list_connectivity_tests**: List connection monitors.
|
||||
- **azure_get_instance_basic_info**: Read one virtual machine.
|
||||
- **azure_get_instance_group_manager_basic_info**: Read one scale set.
|
||||
- **azure_get_instance_template_properties**: Read one template spec or gallery image.
|
||||
- **azure_get_disk_basic_info**: Read one disk.
|
||||
- **azure_get_cluster**: Read one AKS cluster.
|
||||
- **azure_get_service**: Read one app.
|
||||
- **azure_get_sql_instance**: Read one database server.
|
||||
- **azure_get_topic**: Read one messaging resource.
|
||||
- **azure_get_role**: Read one role definition.
|
||||
- **azure_get_alert_policy**: Read one alert rule.
|
||||
- **azure_get_connectivity_test**: Read one connection monitor.
|
||||
- **azure_list_assets**: List every resource in scope, or one resource type.
|
||||
- **azure_get_node_pool**: Read one AKS node pool.
|
||||
- **azure_list_commitments**: List reserved capacity orders, Azure's committed-use discounts.
|
||||
- **azure_get_k8s_version**: List the Kubernetes versions AKS offers in one location.
|
||||
- **azure_list_subscriptions**: List Event Grid event subscriptions.
|
||||
- **azure_list_deny_policies**: List deny assignments.
|
||||
- **azure_list_metric_descriptors**: List the metrics one resource publishes.
|
||||
- **azure_list_timeseries**: Read metric values for one resource.
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Authentication
|
||||
|
||||
This server uses Bearer token authentication for MCP protocol messages.
|
||||
|
||||
```bash
|
||||
# Test with authentication
|
||||
curl -X POST http://localhost:8116/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:8116`)
|
||||
- **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 |
|
||||
| `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:8116 MCP_REGISTRATION_API_KEY=<the key> pytest tests/ -v
|
||||
```
|
||||
|
||||
A check that fails says what to fix. Run it again after you implement your tools, since a tool that
|
||||
reads an environment variable for its credential, or repeats one in an error, fails it. Checks that
|
||||
do not apply (a server with no credential fields) are skipped, not passed. To run it with
|
||||
`REQUIRE_VAULT_CONNECTION=false` on your own machine, set `CONFORMANCE_EXPECT_FAIL_CLOSED=false`.
|
||||
|
||||
---
|
||||
|
||||
## 🚢 Deploying through the tools repository
|
||||
|
||||
To have CI build and deploy this server, put this folder in the root of the
|
||||
`modernization-tools-mcp-servers` repository as `solution-architecture-azure/`, then add it to
|
||||
`mcp_servers_to_deploy.yaml` in that repository with the instances it should
|
||||
run on:
|
||||
|
||||
```yaml
|
||||
- name: "solution-architecture-azure"
|
||||
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:8116/health
|
||||
|
||||
# List tools
|
||||
curl -X POST http://localhost:8116/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)
|
||||
@@ -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
|
||||
@@ -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: "solution-architecture-azure"
|
||||
SERVER_PORT: "8116"
|
||||
|
||||
# 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"
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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>
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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)
|
||||
Reference in New Issue
Block a user